Use tools to automatically generate Wiki e.g. MKdocs?

[alexandreroutier]

MKdocs (https://www.mkdocs.org/) ables to generate static wiki from Markdown files. The default theme is not very lovely but people developed a great theme called Material with a set of predefined colors: https://squidfunk.github.io/mkdocs-material/ (play with Primary colors section)

(For an overview of themes, see e.g. https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)

How to install mkdocs with Material theme?

pip install mkdocs-material

How do I generate a Wiki from my markdown file(s) ?

See Getting Started for details.

MKdocs needs a YAML file to understand which files be on the Wiki and following which hierarchy. MKdocs expects 2 minimum things:

• Markdown files to be located in a default folder named docs (can be changed using docs_dir value)
• The main page will be named index.md

Assuming the following files:

├── docs
│   ├── ReadMe.md
│   └── index.md
└── mkdocs.yml

The resulting configuration file will look like:

# Project information
site_name: 'Tutorials and resources'
repo_name: 'learn-neuroimaging/tutorials-and-resources'
repo_url: 'https://github.com/learn-neuroimaging/tutorials-and-resources'
# docs_dir: alternative_path # docs/ is the default folder

# This will use Material them
theme:
  name: 'material'
  language: 'en'
  palette:
    primary: 'light blue'
    accent: 'light blue'

# Pages
nav:
  - Learning neuroimaging: "ReadMe.md"

Examples

BIDS

Wiki: https://bids-specification.readthedocs.io/ Source: https://github.com/bids-standard/bids-specification

An example of wiki project with Clinica:

Wiki: http://www.clinica.run/doc/ Source:

git clone https://github.com/aramis-lab/clinica.wiki.git
cd  clinica.wiki
pip install -r requirements.txt # will install mkdocs-material and other few things
# Test locally
mkdocs serve

[Remi-Gau]

This was OK for me.

I think that if we want to add to a readme or a contribution guide, we might just need to a mention of how to run it locally. Sure it is in the MKDOCS doc but having the command just in our readme directly might save some people the trouble. Or might contributors aware that viewing things locally is even a possibility: not sure everyone knows that. :-)

[Remi-Gau]

This was OK for me.

I think that if we want to add to a readme or a contribution guide, we might just need to a mention of how to run it locally. Sure it is in the MKDOCS doc but having the command just in our readme directly might save some people the trouble. Or might contributors aware that viewing things locally is even a possibility: not sure everyone knows that. :-)

Just saw that you have put the mkdocs serve in your example... :-)