Improve this guide!¶
Send help pls.
Local development¶
Install Material for MkDocs, clone the repo and serve the site locally:
python3 -m venv venv
source venv/bin/activate
pip install mkdocs-material
git clone https://github.com/pietro-nobili-SDG/dsdocs.git
cd dsdocs
mkdocs serve
Project layout¶
The folder structure is something like this:
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
and it's mostly reflected in the navigation bar on the left, but it's not required.
Add a markdown page¶
To add a new topic, create the folder inside docs,
and an index.md file for that topic.
For example, to add some info related to Databricks,
which is a general tool,
create the file
Then add the topic to the navbar:
open mkdocs.yml, look for the nav: section,
and add the new file
As more information is added to the general page for that topic,
at a certain point it makes sense to split it in several pages.
Leave a small introduction on what the tool does in index.md
and create more specific files as needed.
Then, add them to the navbar.
nav:
- Tools:
- Databricks:
- tools/databricks/index.md
- Scheduling: tools/databricks/scheduling.md
- Notebook: tools/databricks/notebook.md
This will result in a navbar that has togglable a Databricks entry:
when clicked, the databricks/index.md page will be shown,
and the nested labels will be shown.
Add a html page¶
To link an external html page,
add the .html file in the same folder where the link will be used
and simply refer to it in a markdown file:
Material for MkDocs¶
For the full documentation visit MkDocs and Material for MkDocs.
For a short gallery of useful mkdocs-material features visit the MkDocs + material page in this guide.