72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
# 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 |