Commit 8c19c284 authored by Jorge Tardío Rubio's avatar Jorge Tardío Rubio
Browse files

README added

parent f35ec821
# Mkdocs Material Design Template
## Introduction
The purpose of this repository is to show a template to document a project with mkdocs and generate a pdf using pandoc and a latex template. The theme of mkdocs is Material for MkDocs and recommended latex template is Eisvogel.
## Overview
![Title page of PDF](imgs/eisvogel_title_page.png)
![Content page of PDF](imgs/eisvogel_content.png)
![Content page of PDF](imgs/eisvogel_chapter1.png)
### Mkdocs
[Mkdocs](https://www.mkdocs.org/) is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration.
### Material for MkDocs
[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) is a theme for MkDocs, a static site generator geared towards (technical) project documentation.
### Pandoc
Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library.
### Eisvogel
[Eisvogel](https://github.com/Wandmalfarbe/pandoc-latex-template) is a clean pandoc LaTeX template to convert your markdown files to PDF or LaTeX. It is designed for lecture notes and exercises with a focus on computer science. See the [custom templates variables](https://github.com/Wandmalfarbe/pandoc-latex-template#custom-template-variables).
## Installation
### Docker (recommended)
Use the image jtr0/mkdocs-material or the oficial image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/) to serve, build or deploy the docs. Mount the folder where your mkdocs.yml resides as a volume into /docs:
- Start development server on [http://localhost:8000](http://localhost:8000):
```bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```
- Build documentation:
```bash
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
```
### Pip
- **Requirements**. Install requirements to run the docs:
```bash
pipenv lock --requirements
```
- **Pipenv**. Add packages to the project with Pipenv:
```bash
# Install pipenv
pip install pipenv
# Install a package for the project
pipenv install <package>
# Activate Virtual Env
pipenv shell
# Desactivate Virtual Env
exit
# Run a script in the virtual env
pipenv run python <script.py>
# Generate `requirements.txt`:
pipenv lock --requirements
```
## Plugins
By default, [mkdocs-minify-plugin](https://github.com/byrnereese/mkdocs-minify-plugin) and [mkdocs-redirects](https://github.com/datarobot/mkdocs-redirects) are installed in oficial docker image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/).
### mkdocs-pandoc-plugin
Use [mkdocs-pandoc-plugin](https://pypi.org/project/mkdocs-pandoc-plugin/) and generate a pdf or other output with pandoc. Active the opction with the environmental variable `ENABLE_PANDOC_EXPORT` set to 1.
### mkdocs-git-revision-date-plugin
Use [mkdocs-git-revision-date-plugin](https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin)
## Deploy
### Gitlab Pages
Generate a `.gitlab-ci.yml`
### GitHub Pages
- Deploy documentation to GitHub Pages (not tested):
```bash
docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy
```
## Generate pdfs with pandoc and latex
- Build images:
```bash
sh scripts/build_dockers.sh
```
- Generate pdfs:
```bash
sh scripts/pdf_local_generator.sh
```
# Example of eisvogel template generation
```
docker run --rm -it -v ${PWD}:/data jtr0/latex-pandoc pandoc -N --template=eisvogel.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdfs/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/eisvogel_template.pdf
```
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment