Metadata-Version: 2.1
Name: aqui-brain-dump
Version: 0.1.2
Summary: Create a static website based on notes from a digital garden
License: MIT
Author: Aquiles Carattino
Author-email: aqui.carattino@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: Jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: Markdown (>=3.4.3,<4.0.0)
Requires-Dist: MarkupSafe (>=2.1.3,<3.0.0)
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: beautifulsoup4 (>=4.12.2,<5.0.0)
Requires-Dist: markdown-checklist (>=0.4.4,<0.5.0)
Requires-Dist: md4mathjax (>=0.1.3,<0.2.0)
Requires-Dist: pyembed (>=1.3.3,<2.0.0)
Requires-Dist: pyembed-markdown (>=1.1.0,<2.0.0)
Requires-Dist: python-frontmatter (>=1.0.0,<2.0.0)
Requires-Dist: text-unidecode (>=1.3,<2.0)
Description-Content-Type: text/markdown

# Static Website Builder

This is a very simple static website builder, which I use for building [aquiles.me](https://www.aquiles.me). The idea is to grab a bunch of markdown files and render them as HTML files. 

Building from scratch was easier than trying to adjust existing solutions to my own needs. I a releasing this package mostly to help others learn. 

The template was built using TalwindCSS, and is processed with PostCSS to make it minimal (11kb without compressing). 

## Entry Point
The program can be triggered by running the following command:

```bash
$ brain_dump
```

It assumes the following:

* Content Folder: ``content``
* Template Folder: ``templates``
* Static Folder: ``static``
* Output Folder: ``output``

You can see the [main function](https://github.com/aquilesC/static_website_builder/blob/master/aqui_brain_dump/main.py) to understand what it does.

## Core Ideas
I built this static generator so that small notes can quickly find their way online, lowering my barrier to pushing content to a website. Therefore, it all revolves around using plain markdown files (I author them using Obsidian), and compiling using two simple templates: one for the index page and one for each note/article. 

Each note that ends with ``.md`` will be transformed into a folder such as as ``/note/index.html`` and spaces will be transformed to underscores. 

!! warning
    I am not dealing with non-ascii characters in any way, which is a problem for URL's

Each note can have internal links, in which I use the wikilink syntax: ``[[ ]]``. Each link is then appended to the target page, so that lists of backlinks can be built. I find the idea of backlinks crucial for lowering the barrier, since new content can be automatically be shown on older content. 

Also, links to non-existing pages will force the creation of an 'empty' node that only displays backlinks. 

## Extra Markdown
There are some custom solutions embedded into the program. For example, wikilinks parse the presence of ``|`` as a separator for the href. In this way, ``[[target|link]]`` will show up as ``link`` but will be targeted at ``target``. The wikilinks also remove all the spaces and transform them to underscores to be consistent with how I deal with URL's. 

The frontmatter is separated using an initial ``---`` and final ``---``. The keyowrds used for the moment are: ``title`` and ``description``, which are used for the meta tags of the html, ``epistemic``, which adds a note at the top of each article to display the [epistemic status](https://www.aquiles.me/epistemic_status). Other fields are accepted but are not currently used when generating content.

I also make use of ``admonition`` to include images of different widths. The ``style.css`` defines two types of images: medium and small that can be used by inserting something like this in the markdown file:

    !!! image small
	    ![Aquiles Carattino](/Aquiles_Carattino.jpg) 

## Git-based creation and modification dates
Since my working flow is based on git, I use it to compute the creation and modification dates of each file. It is not super accurate, since it measures the moment a file was added to git and not really created on the computer. Normally the offset is lower than a day. This approach seems to give more consistent results than using the operating system's dates, and is compatible with Netlify. 

You can read more on my [about page](https://www.aquiles.me/about).

## License
The code is released under BSD 3 Clause License. See LICENSE for more information. You are free to use and re-distribute, provided that you aknowledge my work. Seems fair enough. 

Of course, if you are trying to learn from the program, or building on it, don't hesitate to reach out at **hey@aquiles.me** 
