https://github.com/TGITS/fun-with-mkdocs

Example project that demonstrate the use of mkdocs and material for mkdocs
https://github.com/TGITS/fun-with-mkdocs

Last synced: 5 months ago
JSON representation

Example project that demonstrate the use of mkdocs and material for mkdocs

• Host: GitHub
• URL: https://github.com/TGITS/fun-with-mkdocs
• Owner: TGITS
• License: cc0-1.0
• Created: 2023-12-22T15:42:10.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-02-17T12:17:07.000Z (about 1 year ago)
• Last Synced: 2024-08-09T02:18:48.244Z (8 months ago)
• Size: 376 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• jimsghstars - TGITS/fun-with-mkdocs - Example project that demonstrate the use of mkdocs and material for mkdocs (Others)

README

        
# fun-with-mkdocs

Example project that demonstrate the use of mkdocs and material for mkdocs

## Using with Python

If you already have Python installed on your system or you prefer using mkdocs without using Docker, the recommended steps are the following :

* Create a virtual environment with `venv` (it is bundled with Python) before installing **MkDocs** :

  * In a shell, at the root of the directory in which you want to install mkdocs, type : `python -m venv venv --prompt="mkdocs"`

  * A `venv` directory should be created : add this directory to the `.gitignore`

* Activate the virtual environnement : `venv\Scripts\activate`

* Install **MkDocs (with Material)** with `pip`

  * `pip install mkdocs-material`

  * Now **MkDocs** is installed in your virtual environment

* When you have finished your work session in the shell, remember to deactivate your virtual environment : `venv\Scripts\deactivate`

When the installation is done, the following commands are available :

* Initialization : `mkdocs new `

  * Only to initialize the MkDocs project, you should execute this command only once.

* Previsualization : `mkdocs serve` or `mkdocs serve --dirtyreload` if you only want to update the current page (incomplete but faster build of the site).

* Building of the site : `mkdocs build`

  * The HTML files of the site are generated in the directory `site/fun-with-mkdocs`

  * They can be open directly with your browser.

Remember to activate your virtual environment before running the **MkDocs** commands : `venv\Scripts\activate`

And remember to activate it when you have finished your work session (if you forgot it is the end of the world, particularly if you close your shell) : `venv\Scripts\deactivate`.

## Using with Docker

[MkDocs](https://www.mkdocs.org/) can be used without installation with [Docker](https://www.docker.com/).

* To initialize the site, in the directory in which you want to create if : `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .`

* Previzualisation on `localhost:8000` : `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material`

* Building of the site : `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build`

  * The HTML files of the site are generated in the directory `site/fun-with-mkdocs`