This project provides a template of static documentation website for MkDocs using a ReadTheDocs-like theme by default.
It nests Reveal.js for integrating nice-looking slideshows in order to make more didactical documentations.
An example can be found at dhondta/pentest-for-beginners
.
This template includes pluggable versions of the following projects:
- Reveal.js: for making slideshows inside the documentation website
The following extra Reveal.js plugins are available for embedding extra items inside the presentations:
- flowchart-js (using Flowchart.js): for making flowcharts with the DOT language
- jsmind (using JSMind): for making mindmaps with the DOT language
- quizz (for making stateless quizzes)
-
mkdocs.yml
: the MkDocs configuration fileIn this file, you can configure the author name (for displaying in the footer), your email address but you will also have to use it for defining the documentation pages you want to add.
-
src
: your Markdown content filesIn this folder, you can add your Markdown files you will point to in the configuration file.
slides
: your Markdown slide content files
Advice: Each slideshow can contain a flowchart, a mindmap or a quizz ; use a folder with the same name than the Markdown page that contains the iframe for grouping the related files. Check the
template
folder inslides
to get started.
-
img
: the images for the documentation (note that this structure is a template and can obviously be adapted, e.g. by putting the images relatively to the content subfolders) -
labs
,exercises
, ...: other content folders
Advice: Keep this structure and work with relative links
theme
: the theme of the documentation website (SHOULD not be modified, unless contributing to this project)
$ git clone https://github.com/dhondta/mkdocs-revealjs-template
[...]
$ cd mkdocs-revealjs-template
$ mv src_example src
$ mv mkdocs.yml.template mkdocs.yml
$ cp src/slides/template.md src/slides/intro.md
$ cp -r src/slides/template src/slides/intro
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I ###### ##:##:## server:283] Serving on http://127.0.0.1:8000
[I ###### ##:##:## handlers:60] Start watching changes
For each page you create, use this methodology:
- Copy the Web page template
$ cp src/slides/template.md src/slides/intro.md
$ cp -r src/slides/template src/slides/intro
Note: By convention,
md
files are MkDocs pages and are named accordingly. A folder is created with the same name (without the.md
, of course) and a file namedslides.mdtxt
holds the Reveal.js slideshow.
- Reference the new page in
mkdocs.yml
$ gedit mkdocs.yml
# Reference: http://mkdocs.org
site_name: [...]
site_author: [...]
pages:
- 'Introduction': index.md
- 'Introduction':
- 'A sample slideshow': slides/intro.md
extra:
mailto: [...]
[...]
Note: The first occurrence creates a hyperlink for "Introduction". The second occurrence defines subsections accessible through a dropdown list that can be opened using a caret that is displayed when subsections exist. So, for a section without subsections, omit the second occurrence and for subsections without the main section having a hyperlink, omit the first occurrence.
- Edit items
$ gedit src/slides/intro/*
For more information about how to tune your documentation, please consult these tutorials:
- Tuning the MkDocs web pages
- Tuning the Reveal.js slideshows
- Writing your docs
- Building Product Documentation with MkDocs
- Reveal.js - The HTML presentation framework
- Reveal.js on GitHub
Note: The page is visited by using a directory URL, e.g.
http://localhost:8000/slides/intro/
. This is because the parameteruse_directory_urls: true
is defined inmkdocs.yml
. It is strongly advised not to change this parameter and to keep using this behaviour.
Additional information
Of course, as Markdown can be too limited for some use cases, HTML can be used to insert more sophisticated items.
Reveal.js slideshows are embedded in the documentation by using an iframe
like follows:
<iframe class="slideshow" src="./slideshow.html" frameborder=0></iframe>
Sometimes, it can be useful to hide some piece of text, e.g. when showing a trace of actions done by a tool while it should not be deductible to know when the tool was run, or on which target, and so forth. For the purpose of easilly hiding patterns of text recursively in a whole folder, DocTextMasker can be used.
For contributions or suggestions, please open an Issue and clearly explain, using an example or a use case if appropriate.