Contribute to documentation
Files are written with markdown syntax but gitbook allows HTML syntax too.
However, it is not possible to mix the 2 syntaxes in the same block.
If you want to add internal links, be careful to point to
.html pages corresponding to the
.md pages of the folder.
The Framaprojet doc home page may contain a presentation part + quick start + link to source software and a presentation part of the source software (it can be from the official doc) table of contents with the list of pages found in the submenu on the left.
- Create a branch
- Make changes (commits)
- Ask for a merge request
English and French documentation are completely independent.
The documentation of each Frama project must be recorded in a file
corresponding to the name of the source software (example: Framacarte → in the
In this folder, create an
images folder containing the screenshots
README.md file which will contain the project presentation home page
Then add the Framaprojet in the left column and on the home page,
you must edit the
README.md files (at the root in the
SUMMARY.md, it is not possible to display a tree structure
of more than 2 levels and titles are not taken into account
(they are left only as an indication).
.md link found in this file will be turn into the corresponding
.html file by Gitbook.
Files not found there will be placed in the folder
as simple static files (like images)
Create local copy of the documentation
To get a preview of the site rendering it may be useful to install Gitbook locally.
sudo apt-get install nodejs-legacy npm sudo npm install gitbook-cli -g
Clone your documentation fork
git clone https://framagit.org/<user>/framasoft/docs.git
docs folder, proceed to requiered plugins (plugins list and their configuration are in
cd docs gitbook init gitbook install gitbook serve --no-watch
If everything is good (command ends by
Serving book on…), local copy can be found at this adress: http://localhost:4000/
--no-watch option prevents each change in the
files causes an automatic restart of the nodejs server
which can be heavy in the long run.
The more pages, the longer the loading time.
It is better to take the time to finish the changes and restart the server manually when we're done.
If you have a local web server, rather than using the server nodejs, you can also create the site manually with the command:
_book folder wherever you want on your server.