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

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

5 files changed, 42 insertions, 18 deletions

diff --git a/.gitignore b/.gitignore
index 026e6ad..634aaef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ build-dev
 conf/_release.yml
 site/_data/all-pages.yml
 site/_data/tocs
+.fetch.ts
diff --git a/Makefile b/Makefile
index 38d105c..c61608e 100644
--- a/Makefile
+++ b/Makefile
@@ -2,11 +2,14 @@ DOCBUILD=../doctools/webdocs/docbuild
 
 VERBOSE=--verbose
 
+FETCHTS=.fetch.ts
+
 all: help
 
 help: 
 	@echo "Usage:"
 	@echo "- make clean: clean all generated files"
+	@echo "- make fetch: fetch the site if necessary"
 	@echo "- make build: build the site"
 	@echo "- make push: push the built site"
 	@echo "- make serve: serve the site"
@@ -14,20 +17,25 @@ help:
 .PHONY: clean
 clean:
 	$(DOCBUILD) $(VERBOSE) --clean
+	rm -f $(FETCHTS)
+
+$(FETCHTS): $(wildcard site/_tocs/*/fetched_files.yml)
+	$(DOCBUILD) $(VERBOSE) --fetch --force
+	touch $@
 
 .PHONY: fetch
-fetch:
-	$(DOCBUILD) $(VERBOSE) --fetch --force 
+fetch: $(FETCHTS)
+	@echo "Fetched files up to date."
 
 .PHONY: build
-build: fetch
+build: $(FETCHTS)
 	$(DOCBUILD) $(VERBOSE) --build
 
 .PHONY: push
-push: fetch
+push: $(FETCHTS)
 	$(DOCBUILD) $(VERBOSE) --build --push
 
 .PHONY: serve
-serve: fetch 
+serve: $(FETCHTS)
 	$(DOCBUILD) $(VERBOSE) --build --serve
 
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
 
diff --git a/site/.htaccess b/site/.htaccess
index 0bbfea2..61548b8 100644
--- a/site/.htaccess
+++ b/site/.htaccess
@@ -48,6 +48,11 @@ RewriteEngine on
 #      NE - no escaping special characters
 
 # 302 (temporary):
+#     *.md -> *.html
+RewriteRule ^(.*?)\.md$ $1.html
+#RewriteRule ^.*docs/(.*?)\.md$ {{site.baseurl}}/docs/$1.html [R=302]
+
+# 302 (temporary):
 #
 #     docs/         -> docs/[default language]/latest/
 #     docs/*        -> docs/*/latest/
diff --git a/site/_tocs/getting_started/fetched_files.yml b/site/_tocs/getting_started/fetched_files.yml
index 29425f6..bc4c2ad 100644
--- a/site/_tocs/getting_started/fetched_files.yml
+++ b/site/_tocs/getting_started/fetched_files.yml
@@ -60,7 +60,7 @@ repositories:
     - source: footers/porter-footer.md
       label: Porter board
     - source: footers/raspberrypi-footer.md
-      label: Rasperry PI
+      label: Raspberry PI
     - source: images/RaspberryPi2-ModelB-debug-serial-cable.jpg
       destination: footers/images/RaspberryPi2-ModelB-debug-serial-cable.jpg