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

Initial commit

parents
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"
[packages]
requests = "*"
mkdocs = "*"
mkdocs-material = "*"
mkdocs-material-extensions = "*"
mkdocs-pandoc-plugin = "*"
[dev-packages]
[requires]
python_version = "3.7"
This diff is collapsed.
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
# Example toc 1
\ No newline at end of file
# Example toc 2
\ No newline at end of file
# Plantilla de Mkdocs Material
site_name: Nombre Docs
site_description: Description...
repo_url: https://lab.gsi.upm.es/devops-templates/mkdocs-material
edit_uri: edit/main/docs/
nav:
- Material for MkDocs: index.md
- Bienvenido a MkDocs: en/index.md
- Ejemplo de collapse:
- Ejemplo1: en/toc1.md
- Ejemoplo2: en/toc2.md
theme:
name: material
language: en
include_search_page: true
search_index_only: true
palette:
# Light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
# Dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue
accent: blue
toggle:
icon: material/toggle-switch
name: Switch to light mode
plugins:
- search
- minify:
minify_html: true
minify_js: true
htmlmin_opts:
remove_comments: true
- pandoc:
enabled_if_env: ENABLE_PANDOC_EXPORT
combined: true
combined_output_path: docs.pdf
- git-revision-date:
enabled_if_env: CI
locale: en
markdown_extensions:
- toc:
permalink: "#"
toc_depth: 3
extra:
social:
- icon: fontawesome/brands/gitlab
link: https://lab.gsi.upm.es/devops-templates/mkdocs-material
- icon: fontawesome/brands/gitter
link: https://gitter.im/repo
- icon: fontawesome/brands/docker
link: https://hub.docker.com/r/jtr0
- icon: fontawesome/brands/twitter
link: https://twitter.com/devops
alternate:
- link: /
name: en - English
lang: en
- link: /es/
name: es - español
lang: es
\ No newline at end of file
# 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 | Content |
| :----: | :----: |
| ![Title page of PDF](/imgs/eisvogel_title_page.png){width=300px} | ![Content page of PDF](/imgs/eisvogel_content.png){width=300px} |
| Images | Chapther One |
| :----: | :----: |
|![Images](/imgs/eisvogel_chapter1.png){width=300px} |![Chapther One](/imgs/eisvogel_chapter1.png){width=300px} |
### 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
```
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
```
site_name: Docs Name
site_description: Description...
repo_url: https://lab.gsi.upm.es/devops-templates/mkdocs-material
edit_uri: edit/main/docs/
nav:
- Material for MkDocs: index.md
- Welcome to MkDocs: en/index.md
- Collapse example:
- Example1: en/toc1.md
- Example2: en/toc2.md
theme:
name: material
language: es
include_search_page: true
search_index_only: true
palette:
# Light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
# Dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: blue
accent: blue
toggle:
icon: material/toggle-switch
name: Switch to light mode
plugins:
- search
- minify:
minify_html: true
minify_js: true
htmlmin_opts:
remove_comments: true
- pandoc:
enabled_if_env: ENABLE_PANDOC_EXPORT
combined: true
combined_output_path: docs.pdf
- git-revision-date:
enabled_if_env: CI
markdown_extensions:
- toc:
permalink: "#"
toc_depth: 3
- attr_list
extra:
social:
- icon: fontawesome/brands/gitlab
link: https://lab.gsi.upm.es/devops-templates/mkdocs-material
- icon: fontawesome/brands/gitter
link: https://gitter.im/repo
- icon: fontawesome/brands/docker
link: https://hub.docker.com/r/jtr0
- icon: fontawesome/brands/twitter
link: https://twitter.com/devops
alternate:
- link: /
name: en - English
lang: en
- link: /es/
name: es - español
lang: es
\ No newline at end of file
#
# These requirements were autogenerated by pipenv
# To regenerate from the project's Pipfile, run:
#
# pipenv lock --requirements
#
-i https://pypi.org/simple
beautifulsoup4==4.9.3
certifi==2020.12.5
chardet==4.0.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'
click==7.1.2; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'
future==0.18.2; python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'
idna==2.10; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
importlib-metadata==3.10.1; python_version < '3.8'
jinja2==2.11.3; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'
joblib==1.0.1; python_version >= '3.6'
livereload==2.6.3
lunr[languages]==0.5.8
markdown==3.3.4; python_version >= '3.6'
markupsafe==1.1.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
mkdocs-material-extensions==1.0.1
mkdocs-material==7.1.1
mkdocs-pandoc-plugin==1.0.0
mkdocs==1.1.2
nltk==3.6.1
pygments==2.8.1; python_version >= '3.5'
pymdown-extensions==8.1.1; python_version >= '3.6'
pyyaml==5.4.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'
regex==2021.4.4
requests==2.25.1
six==1.15.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2'
soupsieve==2.2.1; python_version >= '3.0'
tornado==6.1; python_version >= '3.5'
tqdm==4.60.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
typing-extensions==3.7.4.3; python_version < '3.8'
urllib3==1.26.4; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'
zipp==3.4.1; python_version >= '3.6'
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