webdocs: updated README; fix htaccess for local .md files

Change-Id: I9458a663ed1e2df1a38fa606e834b448b2bab312
Signed-off-by: Stephane Desneux <stephane.desneux@iot.bzh>

1 files changed, 22 insertions, 12 deletions

diff --git a/README.md b/README.md
index 530d620..ba608de 100644
--- a/README.md
+++ b/README.md
@@ -13,29 +13,39 @@ See how to install webdocs: read file in doctools/webdocs/README.md
 
 ## configure webdoc
 
-Edit conf/AppDefault
-+ Default configuration consider that webdoc tools  & site are within the same parent directory.
-+ If needed, update Doc_TOOLS to the right path.
+Some default configuration options can be overridden in the project directory. For this, you can adjust the configuration file conf/AppDefault.js
+
+Other configuration files in conf/ starting by an underscore (_) are used by Jekyll. Some options may also be adjusted in particular in conf/_config.yml.
 
 ## generate a 1st site from your template
 ```
- ./build --clean  # deleted all generated file if any
- ./build --fetch [--force]  # collect doc from github (fetch list in site/_tocs/*/fetch_files.yml)
- ./build --build --serve --watch --incremental # build config/tocs, generate html and start a local webserver
+ ../doctools/webdocs/docbuild --clean  # deleted all generated file if any
+ ../doctools/webdocs/docbuild --fetch [--force]  # collect doc from github (fetch list in site/_tocs/*/fetch_files.yml)
+ ../doctools/webdocs/docbuild --build --serve --watch --incremental # build config/tocs, generate html and start a local webserver
+
+ xdg-open http://localhost:4000
 
-  browser on http://localhost:4000
+ ../doctools/webdocs/docbuild --push --verbose # push generated to production webserver (check conf/AppDefault 1st)
+```
 
- ./build --push --verbose # push generated to production webserver (check conf/AppDefault 1st)
+Alternatively, a Makefile can be used and defines the most common operations:
+```
+ make fetch
+ make build
+ make push
+ make serve
+ make clean
 ```
 
 ## start writing documentation
 
-- the directory ./site holds your website contend
+- the directory ./site holds your website content
 - site/* directories not prefixed with "_" represent en entry within the menu
-- site/_* directory contains template, configuration, options
+- site/_* directories contain template, configuration, options used by Jekyll
 - site/_data is a special directory that hold both static and generated files to adjust page/site values within html pages
-- site/_tocs/*/toc_VERSION_LANGUAGE.yml TOC(TableOfContend) and GitFetch definition (ex: appfw)
-- site/_layouts holds page template 
+- site/_tocs/*/toc_VERSION_LANGUAGE.yml TOC(TableOfContent) and Fetch definitions
+- site/_layouts and site/_includes holds page template 
+- site/static holds assets (static images, CSS etc.)
 
 - register at https://community.algolia.com/docsearch/ and update your apikey into conf/_config.yml