A simple static site generator
Project description
QRN: A simple, highly opinionated static site generator
QRN is a static site generator that is as simple as I can make it while still being useful. QRN assumes that most of your content is in markdown format, that you are using sass/scss or plain old css for styling. QRN is also geared towards modest sized content, the kind of thing you might find in a personal blog.
QRN also supports a simple but flexible layout/templating system that let's you specify a standard HTML "frame" around your content and also embed executable Python code in the content.
A key feature of QRN is that it has very few external dependencies. QRN is written in a fairly generic Python 3 and requires:
- The PyYAML Python library.
- An external program that turns markdown into HTML (currently pandoc).
- And external program that turns scss/sass into css (currently sass).
That's it. What this means is that QRN is easy to set up and (I hope) will continue to work over time as libararies and packages change.
What does QRN mean?
Ham radio operators use a shorthand code that has its origins in the early days of telegraphy. QRN is the code that means "I am troubled by static noise."
Using QRN
QRN works like most static site generators: You prepare a directory with roughly the content you want to show up in your final site. When you run QRN it transforms your source content into a final output site that you can then deploy. The value of QRN is that it performs various transformation as it does the copying:
- QRN knows how to tranform markdown files into html.
- QRN knows how to do "include" processing on your content so that you can write the common parts of your site once.
The key idea behind QRN is that it is extremely opinionated about a few things -- mostly around a some key naming conventions and how those files are processed into your final static webstite.
Specifically:
- QRN wants you to put the source for your site under a directory called
src. - QRN generally ignores files and directories whose names start with an underbar (.e.g.
src/_save). - QRN wants you to put the source for all included files and layouts (see below) in
src/_layouts. - When you run QRN it will put the resulting processed, read-to-go site in a directory called
build. - QRN will run all files with a
.htmlor.xmlextension through theepyprocessor (see below). - QRN will run all files with a
.hamlextension through thepamlprocessor (see below). - QRN will run all files with a
.mdextension through theepyprocessor and then convert it to HTML. - QRN will run all files with a
.sassor.scssextension through thesassprocessor. - Otherwise, QRN will just copy files from
srctobuild.
File headers and layouts.
In general, QRN will recognize YAML headers at the beginning of .md, .html, .xml and .haml files. The headers are set off from the file content with three dashes:
---
title: A simple html file.
date: klsdfklj
---
<html>
<body>
<title>A simple html file.</title>
</body>
</html>
The EPy Processor
As mentioned above, QRN runs .md, .html and .xml files through the Embedded Python (or EPy) processor.
EPy allows you to embed code that is evaluated at site build time in your content.
EPy uses the common text <%= some_code() %> more text syntax, reminencent of
Embedded Ruby. Specifically:
<%= some_code() %>will insert the result of evaluating the Python code into the text. Thus1 <%= 100/50 %> 3will result in1 2 3.<%! other_code() !%>will simply evaluate the Python code and ignore the result.
Python's indentation based approach to syntax presents a special challenge to EPy: Requiring significant whitespace
in embedded code would be error prone and confusing. Instead, EPy strips off leading whitespace and relies on the
training :'s to open code blocks and a special <%! end %> directive to close them. Here, for example is a
loop in EPy:
<%! for x in range(1): %>
The number is <%= x %>
<%! end %>
And an if statement in EPy:
<%! count = 0 %>
<%! if count: %>
The count is non-zero.
<%! else: %>
The counts is zero.
<%! end %>
Note that the <%! end %> does not appear in the actual Python code. It
is just a marker that the if or for has ended.
The Paml Processor
Similarly, QRN includes a "Paml" processor. Paml is like Haml, but it uses Python in place of Ruby. Other than that syntax is more or less Haml. Here's an example:
---
kind: partial
---
.twelve.columns
%ul.menu
%li.menu
%a{"href": "/index.html"} Contents
%li.menu
%a{"href": "/credit.html"} Credits
%li.menu
%a{"href": "/license.html"} License
%li.menu
%a{"href": "/205-0.txt"} Original File
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file qrn-0.20.1.tar.gz.
File metadata
- Download URL: qrn-0.20.1.tar.gz
- Upload date:
- Size: 18.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c4542ff9a732591622652f88cfd2d9625220faa6ce2917bab27864c372c6f5fa
|
|
| MD5 |
9c3dea0643d54c66cd724406d0ee9d72
|
|
| BLAKE2b-256 |
0fd2d6254a8583d9d6b74cbcd84bdb6b6e755c7e5a8afe8750e770e6da079eaa
|
File details
Details for the file qrn-0.20.1-py3-none-any.whl.
File metadata
- Download URL: qrn-0.20.1-py3-none-any.whl
- Upload date:
- Size: 19.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bfd8ab88a5035c5fe282f17a51cecd09e0164c22120f7094d7646ae4d4150b1d
|
|
| MD5 |
60cf56cc6cb724009aad5eac4c0e2ca0
|
|
| BLAKE2b-256 |
304ec1f4b8953f8081032ae8ef11293e7f4143ee1e126aa8b6f827c7eadd3f01
|
