EMS-ESP Documentation

This is the official documentation for EMS-ESP and hosted on https://docs.emsesp.org

Built on MkDocs using Material for MkDocs theme and borrowed from Tasmota.

Editing Articles

Edit only articles in /docs folder.

All paths are relative.

Use strict markdown syntax. See Markdown Cheatsheet for a quick reference.

Markdown Enhancements

Admonitions

Reference of all possibilities

Definition Lists

Usage

Tabs

Start each tab section with === "Tab title" and indent the tab content by 4 spaces. More information...

Warnings/Tips

!!! tip
    A tip

!!! warning
    A warning

!!! info "some info"

!!! note
    just a note

Superscript text

Enclose text in ^ ^ to superscript it. Example H^2^0 renders H²O

Installing

Easiest way is to run pip as a module (https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment). On Linux to install pip and this projects dependencies use:

• python3 -m venv venv to create the virtual environment
• source ./venv/bin/activate to enter it
• pip install wheel and pip install -r requirements.txt to install the libraries

Testing locally

• source ./venv/bin/activate to go into the virtual environment
• pip install -r requirements.txt to refresh latest libs
• mkdocs serve to build the documentation
• http://127.0.0.1:8000
• TIP: comment out the git-committers and git-revision-date-localized sections in mkdocs.yml to speed up the build and prevent exceeding the GitHub API calls, but remember to uncomment it before committing

Production

Format the .md files using prettier:

npx prettier --write docs/*.md

Fix spellings:

npx cspell "**"

After checking in your changes, Cloudflare Pages will automatically build and deploy the changes to https://docs.emsesp.org.