update README.md

README.md

@@ -2,7 +2,7 @@
 
 ---
 
-Example [Hugo] website using GitLab Pages.
+This is a static website made with [hugo](https://gohugo.io).
 
 Learn more about GitLab Pages at https://pages.gitlab.io and the official
 documentation https://docs.gitlab.com/ce/user/project/pages/.
@@ -21,30 +21,66 @@ documentation https://docs.gitlab.com/ce/user/project/pages/.
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## GitLab CI
 
-This project's static Pages are built by [GitLab CI][ci], following the steps
-defined in [`.gitlab-ci.yml`](.gitlab-ci.yml).
+## Structure
+
+Almost all pages are in the [content/{language}](content/) subdirectories.
+
+Some translations belong to the website and are in the [i18n](i18n/)
+subdirectory, while some others belong to the theme (and are within it).
+
+The theme(s) are in the [themes](themes/) subdirectory (and they should be git submodules).
+
+(Alas) There are still some interdependencies between the themes and the hugo website and
+its content :
+ * the theme use the website images.
+ * Some descriptions are in the theme while they could have been in the website,
+   or vice versa.
+
+## Languages feature - i18n support
+
+When you choose a language in the menu bar, you switch content and should translate each page into all languages.
+
+Fortunately our readers use to read multiple languages, and for the more dynamic
+part of content, which are blog, events and training pages, the theme manage the
+**lang** field present in [yaml
+headers](https://cran.r-project.org/web/packages/ymlthis/vignettes/yaml-fieldguide.html).
+
+Then if you want a page written in English, to be displayed in the "French"
+website, just create a symlink from the French part, to this English page. Or
+vice versa.
+
+> $ cd content/french/blog/
+
+> $ ln -s ../../english/blog/1970-01-01-my-first-article.md
+
+## Develop and test this website locally
 
-## Building locally
+You should use a text editor which support [Markdown](https://en.wikipedia.org/wiki/Markdown)
+syntaxes ([vim](https://www.vim.org/), etc.)
 
-To work locally with this project, you'll have to follow the steps below:
+Then you should install [hugo](https://github.com/gohugoio/hugo/releases).
 
-1. Fork, clone or download this project
-1. [Install][] Hugo
-1. Preview your project: `hugo server`
-1. Add content
-1. Generate the website: `hugo` (optional)
+Then you should run:
+
+> $ hugo server -D
+
+To tell hugo to generate the static website, and make it run on your
+[localhost](https://en.wikipedia.org/wiki/Localhost), with the draft pages
+enabled.
 
 Read more at Hugo's [documentation][].
 
+## GitLab CI
+
+This project's static Pages are built by [GitLab CI][ci], following the steps
+defined in [`.gitlab-ci.yml`](.gitlab-ci.yml).
+
 ### Preview your site
 
 If you clone or download this project to your local computer and run `hugo server`,
 your site can be accessed under `localhost:1313/hugo/`.
 
-The theme used is adapted from http://themes.gohugo.io/beautifulhugo/.
-
 ## GitLab User or Group Pages
 
 To use this project as your user/group website, you will need one additional
@@ -64,14 +100,6 @@ If you forked this project for your own use, please go to your project's
 **Settings** and remove the forking relationship, which won't be necessary
 unless you want to contribute back to the upstream project.
 
-## Troubleshooting
-
-1. CSS is missing! That means two things:
-
-    Either that you have wrongly set up the CSS URL in your templates, or
-    your static generator has a configuration option that needs to be explicitly
-    set in order to serve static assets under a relative URL.
-
 [ci]: https://about.gitlab.com/gitlab-ci/
 [hugo]: https://gohugo.io
 [install]: https://gohugo.io/overview/installing/
@@ -79,3 +107,6 @@ unless you want to contribute back to the upstream project.
 [userpages]: http://doc.gitlab.com/ee/pages/README.html#user-or-group-pages
 [projpages]: http://doc.gitlab.com/ee/pages/README.html#project-pages
 [post]: https://about.gitlab.com/2016/04/07/gitlab-pages-setup/#custom-domains
+
+
+