# 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](https://jinja.palletsprojects.com/), 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:

```MARKDOWN
{! path-to-file.md !}
```

The transclusion package also allows for transcluding specific lines:

```MARKDOWN
{! 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`.

```MARKDOWN
---
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