Skip to main content

Compile a set of notes into a browseable website

Project description

Static Website Builder

This is a very simple static website builder, which I use for building 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:

$ brain_dump

It assumes the following:

  • Content Folder: content
  • Template Folder: templates
  • Static Folder: static
  • Output Folder: output

You can see the main function 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. 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.

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 aqui.carattino@gmail.com

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aqui_brain_dump-1.0.6.tar.gz (16.2 kB view details)

Uploaded Source

Built Distribution

aqui_brain_dump-1.0.6-py3-none-any.whl (19.5 kB view details)

Uploaded Python 3

File details

Details for the file aqui_brain_dump-1.0.6.tar.gz.

File metadata

  • Download URL: aqui_brain_dump-1.0.6.tar.gz
  • Upload date:
  • Size: 16.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for aqui_brain_dump-1.0.6.tar.gz
Algorithm Hash digest
SHA256 e1744a0c53c60ec96774eedd07097afea0636251b36ba19aaa2d5e8647c8c578
MD5 192ac8c2b28733f9dfa23e5b0a458b1a
BLAKE2b-256 0060cfda254b2c4144290b7e32cb9c325f045780fef6f6b50b56083a2b25ee9c

See more details on using hashes here.

File details

Details for the file aqui_brain_dump-1.0.6-py3-none-any.whl.

File metadata

File hashes

Hashes for aqui_brain_dump-1.0.6-py3-none-any.whl
Algorithm Hash digest
SHA256 0f3f1180d6c5d14b1ac58aaea1a47bfea9cde5bc2211f00888d144b9917789ab
MD5 1ef0688d3b7c820b3cf702d9866033de
BLAKE2b-256 993335c64b05d2c6b56616d4bc317d801255b4508bb4e65c649387d15aa6395f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page