README.md

Installation

Create a virtual python environment using python -m venv venv Activate the virtual environment using source venv/bin/activate Install the packages using pip install -r requirements.txt

Running

Compile the content into a static site using

python app.py

This creates the "dist" directory, with all of the HTML in there. At the moment, dist is part of the .gitignore!

Writing Content

Within the content directory, you can create/edit markdown files. When compiling the markdown content, app.py will look for jinja templates in the templates directory. If the markdown file is in the root of content, it will try to load a template with the same filename as the markdown file. For instance, about.md will look for about.jinja. If the markdown file is in a subdirectory, it will look for a template with the same name as the subdirectory. At the moment, there is no functionality for deep nested folders. So, recipes/tomato-soup.md wants recipes.jinja. If the template does not exist, the default template is post.jinja.

The project uses Jinja, which allows for extending templates, using variables, looping trough variables, and other funky features!

Additionally, component-inventory.csv is loaded as a dataset.

Transclusion

You'll be able to transclude one markdown file into another, by applying the following syntax:

{! path-to-file.md !}

The transclusion package also allows for transcluding specific lines:

{! path-to-file.md!lines=1  3 8-10  2}

In the example above, it would read the file and include the lines 1, 3, 8, 9, 10, 2.

Metadata

Metadata can be applied to markdown files using FrontMatters YAML. The metadata is accessable in the jinja tempaltes using page.{metadata}. In the example below, this could be, page.title.

---
excerpt: tl;dr
title: Capacitors
type: Capacitor
valueSymbol: unf
description: This is the description
---

Assets

At the moment, the src/assets directory is copied to the dist folder, to apply CSS.

TODO

• update readme
• fix issue with YAML data showing up in included files
• lurk newsletter?
• minify/gzip the HTML
• Export to PDF
• Export to mediawiki
• Export to PDF with zine layout
• last edited date
• Direct link to the markdown file in git?
• Markdown page breaks