awesome-astra/docs

Documentation for awesome Astra

Markdowns to generate the static site https://awesome-astra.github.io/docs

Static site is generated on branch gh-pages using a github action

Run the website locally

1. Installation

python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

(tested with Python 3.10).

2. Run

mkdocs serve

You should be able to access it on http://localhost:8000

Known Issue:

If you get an mkdocs not found error, launch it this way: python3 -m mkdocs serve

3. Instructions

Images

Caution: when running locally, the site is served at http://127.0.0.1:8000/pages/[...] while when deployed, it is at https://awesome-astra.github.io/docs/pages/[...].

This means that if you use "absolute" image URLs such as /img/ETC ETC one will work and the other won't. Unfortunately you have to always use relative paths and climb up the ladder with ../../../../img/ETC ETC !

In other words, if you use "/img/tile-java.png" it will render OK locally and then screw up once deployed.

Also, when calculating the number of .. to insert, count ONE LESS for index.md files as opposed to all other md files: index.md renders as the page for the path containing it (a/b/c/index.md renders the URL a/b/c).

For company logo files, SVG format is preferred to PNG.

WH integration validation

Make sure you pip-install the required package pip install emoji and then you can run: ./wh_validator.py. Not perfect, but it helps.