HTML document, ASCII text, with very long lines (394)
1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
<meta charset="UTF-8">
5
<title>
6
Ampoule
7
</title>
8
<link rel="stylesheet" href="/static/style.css">
9
<meta name="viewport" content="width=device-width, initial-scale=1.0">
10
</head>
11
<body>
12
<header>
13
<nav>
14
<ul>
15
<li><a href="/">Home</a></li>
16
<li><a href="/projects">Projects</a></li>
17
<li><a href="/index">Index</a></li>
18
<li><a href="https://roundabout-host.com/roundabout">Roundabout-host</a></li>
19
</ul>
20
<ul>
21
<li><a href="mailto:root@roundabout-host.com" id="mail-link">root@roundabout-host.com</a></li>
22
</ul>
23
</nav>
24
</header>
25
<main>
26
27
<h1 class="project-title">
28
<span>Ampoule</span>
29
<a href="https://roundabout-host.com/roundabout/ampoule">Repository</a>
30
</h1>
31
<article class="content-area">
32
<p>Ampoule is a lightweight, simple yet flexible, static site generator written in Python.
33
It uses Jinja2 for templating.
34
</p><h2>Features</h2><ul><li><p><strong class="emphasis-2"><em class="emphasis-1">Extremely</em> simple and small</strong>, only a few hundred lines of code.
35
</p></li><li><p><em class="emphasis-1">Only</em> depends on Jinja2, Ruamel YAML, bs4, and colorama.
36
</p></li><li><p><strong class="emphasis-2">Jinja2 templating</strong> will be familiar to Flask users. Now you can use the same templates for
37
both dynamic and static sites.
38
</p></li><li><p>More of <strong class="emphasis-2">a framework</strong>. Sites are generated by a short <strong class="emphasis-2">Python script</strong> that you write to customise
39
what <strong class="emphasis-2">pages</strong> it loads, which <strong class="emphasis-2">templates</strong> it uses, and what <strong class="emphasis-2">data</strong> it passes to them, or create
40
custom <strong class="emphasis-2">filters</strong>, <strong class="emphasis-2">tests</strong> and more.
41
</p></li><li><p>Supports <strong class="emphasis-2">YAML front matter</strong> for pages. It can be accessed using indexing syntax.
42
</p></li><li><p><strong class="emphasis-2">Indexes</strong> can be sorted using a function, iterated and can index any directory, recursively
43
or not. They can also <strong class="emphasis-2">transform URLs</strong> to make them end in ".html".
44
</p></li><li><p><strong class="emphasis-2">Object-oriented</strong> design. The same objects used in that script can also be passed to the
45
templates.
46
</p></li><li><p>Any <strong class="emphasis-2">markup language</strong> can be used, as long as it can be converted to HTML. You just need to
47
configure a filter for it. You can even mix multiple markup languages in the same site.
48
</p></li><li><p>Ships with a light <strong class="emphasis-2">markdown</strong> implementation.
49
</p></li><li><p>Easy to use for <strong class="emphasis-2"><em class="emphasis-1">both</em> programmers and non-programmers</strong>. While you do need a script, you can
50
also use an off-the-shelf one.
51
</p></li><li><p><strong class="emphasis-2">Themes</strong> can be <em class="emphasis-1">exactly how you want</em>.
52
</p></li><li><p>Keeping <strong class="emphasis-2">static files</strong> is easy, because indexes can be static.
53
</p></li><li><p>Static files are always <strong class="emphasis-2">binary</strong> and not templated. The same happens for files that can't be
54
decoded.
55
</p></li><li><p><strong class="emphasis-2">URL</strong>-based definitions. Pages are added using the URL that will be used to access them.
56
</p></li><li><p>Reinforces the <strong class="emphasis-2">web</strong> as a <strong class="emphasis-2">publishing medium</strong>. Static sites are not for everyone, but if you
57
want to <strong class="emphasis-2">publish</strong> something, it's the best way.
58
</p></li><li><p>And GitHub will give you <strong class="emphasis-2">free hosting</strong>, because it's static and <em class="emphasis-1">very cheap to serve</em>.
59
Roundabout-host will soon offer this as well (<code>your.site.roundabout-host.com</code>).
60
</p></li><li><p>It's <strong class="emphasis-2">free software</strong> and available under the <strong class="emphasis-2">GPLv3</strong>.
61
</p></li><li><p><strong class="emphasis-2">No JavaScript</strong> is required, but it can of course be used if you want.
62
</p></li><li><p>Decently <strong class="emphasis-2">fast</strong>: even if you've got a huge site, it should not take more than _30 seconds_.
63
Local rebuilding will also be added. And it's still much faster than any dynamic site.
64
</p></li><li><p>Beautiful logging thanks to colorama.
65
</p></li><li><p>Great for educational use; you can learn <strong class="emphasis-2">Python</strong>, <strong class="emphasis-2">HTML</strong>, <strong class="emphasis-2">CSS</strong>, <strong class="emphasis-2">JavaScript</strong>,
66
and <strong class="emphasis-2">Jinja2</strong> all at once.
67
</p></li><li><p>You can <strong class="emphasis-2">make your site</strong> in <em class="emphasis-1">an hour</em>, and then it's time to focus on writing what you want
68
to publish.
69
</p></li><li><p>If you see fit, it's easy to <strong class="emphasis-2">convert</strong> to a dynamic site. A <strong class="emphasis-2">Flask implementation</strong> is
70
planned.
71
</p></li></ul><h2>Minimal example</h2><pre data-language="python">import string
72
from datetime import datetime
73
import string
74
import ampoule_ssg as ampoule
76
from ampoule_ssg import markdown
77
# Create a site object. This is where we are adding pages to. The argument is the directory
79
# where the site will be built.
80
site = ampoule.Site("my_site")
81
# Use this as "| markdown" in Jinja2 templates to convert any Markdown source to HTML.
84
@site.filter("markdown")
85
def markdown_filter(text):
86
return markdown.markdown2html(text)
87
# Make the URLs web-friendly and make it end in ".html" so it will be correctly formatted
90
# by dumb servers.
91
def article_url(url):
92
url = url.lower().rpartition(".")[0]
93
new_url = ""
95
for i in url:
96
if i in string.ascii_lowercase:
97
new_url += i
98
elif i in string.whitespace:
99
new_url += "-"
100
return new_url + ".html"
102
# Set context that will be passed to all templates. You can still override this.
105
site.context["timestamp"] = datetime.now()
106
site.context["ampoule"] = ampoule
107
# Add the index of articles. In the template, we're looping over it to list them all.
109
articles = ampoule.Index("articles", url_transform=article_url, sort_by=lambda x: x.date)
110
# This makes it take all indexed files and put them under the /articles URL, keeping the
111
# index's URL transformation and placing all of them in the article.html template. This
112
# will be passed as "document" to the template.
113
site.add_from_index(articles, "/articles", "article.html")
114
# Create the main page which has access to the index so it can list all articles.
116
main_page = ampoule.Page(site, "home.html", articles=articles)
117
# Add the page. Note how we're binding it to a path; it will automatically be set as
119
# index.html in that directory, and the URL is site-relative, not the OS root.
120
site.add_page("/", main_page)
121
# Add static files using a recursive static index. It will add all files in the static
123
# directory and all its subdirectories, without putting them into templates. You could
124
# still use them in templates, so you can make a photo gallery or something.
125
site.add_from_index(
126
# We're excluding Markdown files because we're using them as licence information
127
# for when the site is distributed together with the fonts. You can exclude any
128
# file you want using regex.
129
ampoule.Index("static", recursive=True, exclude=r"\.md$"),
130
"/static",
131
# There is no template, because the index is static.
132
static=True
133
)
134
# Makes Ampoule take all pages and put them in a directory.
136
site.build()
137
</pre><h2>More information</h2><h3>Name origin</h3><p>An ampoule is smaller than a flask. Because it is related to Flask (it uses Jinja2) but is
138
a much smaller static version of it, the name makes sense.
139
</p><h3>Why not use Jekyll, Hugo, or Pelican?</h3><h4>Jekyll</h4><p>Jekyll is Ruby, and it's very much Ruby, in fact, it's 17,000 lines of Ruby. Configuration
140
is done only in YAML. It's hard to extend, and the plugin and theme systems are
141
overengineered. It's also limited (no OOP, not even multiple index directories). And for the
142
Flask users like me, it uses a template language that is very similar to Jinja2, but it's
143
not Jinja2, so templates aren't reusable. I've actually used Jekyll, and it's not nice.
144
</p><h4>Hugo</h4><p>Hugo is actually pretty interesting, but it's not as flexible, because it's not scriptable,
145
and a compiled language is not appropriate for this. Did I mention it also has an
146
overengineered theme system? And it's even larger, a whooping 133,000 lines of Go!
147
You can never know it all.
148
</p><h4>Pelican</h4><p>Pelican is opinionated and relies on plugins for everything. It's extremely limited, in
149
fact it can only do blogs. It also can't be portable and implemented in Flask.
150
</p><h3>Why even use a static site generator?</h3><p>You've got two other options. Let's examine them.
151
</p><h4>Dynamic sites</h4><ul><li><p>bloated;
152
</p></li><li><p>slow;
153
</p></li><li><p>requires smart server;
154
</p></li><li><p>requires maintenance;
155
</p></li><li><p>requires security;
156
</p></li><li><p>requires a database;
157
</p></li><li><p>hard to post content;
158
</p></li><li><p>databases can't be managed with git;
159
</p></li><li><p>hard to import content;
160
</p></li><li><p>no free hosting;
161
</p></li></ul><h4>Static sites</h4><ul><li><p>hard to manage layouts;
162
</p></li><li><p>hard to list the content;
163
</p></li><li><p>hard to update indexes;
164
</p></li><li><p>no support for metadata;
165
</p></li><li><p>markup languages must be manually converted;
166
</p></li></ul><p>With a <em class="emphasis-1">generated</em> static site, you get the best of both worlds. It's the best publishing
167
platform, because it's just files.
168
</p><h2>How to install</h2><p>Please note that this is not yet available on PyPI. For now you'll need to download the code
169
(ideally using git) and install it with <code>pip</code> as a local package by giving it the path to the
170
directory containing <code>setup.py</code>.
171
</p><h2>Full documentation</h2><p>To demonstrate just how easy it is, the docs can all fit on one page.
172
</p><h3>class <code>ampoule_ssg.Site</code></h3><p><code>Site</code> is the main class of Ampoule; it represents a single website. It is responsible for
173
handling added pages, the template engine and features, as well as building it.
174
</p><h4>def <code>__init__(self, build_dir: typing.Union[str, bytes, os.PathLike], template_dir: typing.Union[str, bytes, os.PathLike] = "templates")</code></h4><p>Create a new site object. <code>build_dir</code> is the directory where the site will be built.
175
<code>template_dir</code> is the directory where the templates are stored. Both are relative to the
176
script current working directory.
177
</p><h4>def <code>add_page(self, location: typing.Union[str, bytes, os.PathLike], page: typing.union[Static, Page])</code></h4><p>Add a page object to the site at the server-relative URL <code>location</code>. The page object can be
178
either a <code>Static</code> or a <code>Page</code>.
179
</p><h4>def <code>add_from_index(self, index: Index, location: typing.Union[str, bytes, os.PathLike], template: str = None, **kwargs)</code></h4><p>Add all pages from an index to the site with the root at the server-relative URL <code>location</code>.
180
The pages will be rendered with the template <code>template</code> and the context <code>kwargs</code>. will be
181
passed to all of them. If the index is static, the pages will not be rendered with a template,
182
but rather copied as-is.
183
</p><p>For each page, the <code>document</code> object found in the index will be passed to the template under
184
that name.
185
</p><h4>def <code>filter(self, name: str)</code></h4><p>A decorator that registers a filter function with the site. The function should take at least
186
one argument, the value to be filtered, and return the filtered value.
187
</p><h4>def <code>test(self, name: str)</code></h4><p>A decorator that registers a test function with the site. The function should take at least
188
one argument, the value to be tested, and return a boolean.
189
</p><h4>def <code>build(self)</code></h4><p>Build (save) the site to the build directory it was constructed with. This will create the
190
directory if it does not exist, clear it (but not delete it) and then write all the pages.
191
</p><h4><code>context: dict[str, typing.Any]</code></h4><p>A dictionary containing names that are available to all pages. It can be overriden by the
192
page's context or modified at any time.
193
</p><h3>class <code>ampoule_ssg.Page(str)</code></h3><p><code>Page</code> is a class that represents a single page on the site. A page is composed of a
194
template, a document and a context.
195
</p><h4>def <code>__new__(cls, site: Site, template: str, document: Document = None, **kwargs)</code></h4><p>Create a new page object. <code>site</code> is the site object that the page belongs to. <code>template</code> is
196
the template the document will be put in. <code>document</code> is the document object that will be
197
passed to the template. <code>kwargs</code> are names that will be available to the template for
198
additional context.
199
</p><p>If there's no document, it will not be available to the template. This is useful for single
200
pages with fully static content, like a contact page.
201
</p><h3>class <code>ampoule_ssg.Static(bytes)</code></h3><p><code>Static</code> is a class that represents a single static file on the site. A static file is
202
just the content, in binary format, and it doesn't use templating.
203
</p><h4>def <code>__new__(cls, site: Site, document: Document)</code></h4><p>Create a new static object. <code>site</code> is the site object that the static file belongs to.
204
<code>document</code> is the document object that will be written to the file; it can contain any
205
encoding, even text, and will be written as-is.
206
</p><h3>class <code>ampoule_ssg.Index</code></h3><p>An index is a collection of documents that can be iterated over or added to a site using
207
a common template (see <code>ampoule_ssg.Site.add_from_index</code>).
208
</p><h4>def <code>__init__(self, directory: typing.Union[str, bytes, os.PathLike], recursive: bool = False, url_transform: typing.Callable = lambda x: x, sort_by: typing.Callable = lambda x: x.file_name, exclude: typing.Union[str, NoneType] = None, static: bool = False)</code></h4><p>Create a new index. <code>directory</code> is the directory to get content from. If <code>recursive</code> is
209
true, the whole tree of that directory will be indexed. <code>url_transform</code> is a function that
210
will be applied to the file name to get the new file name. Generally you want to set it so
211
it makes them end in <code>.html</code> so dumb servers can serve them correctly. However, for static
212
files you most likely will not set it. <code>sort_by</code> is the key after which to sort the
213
documents after they are indexed; by default it is the file name. <code>exclude</code> is a regular
214
expression that will be used to exclude files from the index. If the index is <code>static</code>,
215
all documents will be parsed as-is, without removing front matter.
216
</p><h4>def <code>__iter__(self)</code></h4><p>Return an iterator for the index.
217
</p><h4>def <code>__next__(self)</code></h4><p>Get the next document in the index.
218
</p><h4>def <code>__repr__(self)</code></h4><p>Return a string representation of the index. It contains the directory and the names
219
of the documents in it.
220
</p><h4>def <code>__len__(self)</code></h4><p>Return the number of documents in the index, that is, its length.
221
</p><h3>class <code>ampoule_ssg.Document</code></h3><p>A document is a file, not rendered, but available for use. It is what is passed to the
222
template as <code>document</code> for processing. Generally, you won't create these yourself, but
223
rather use them as they are returned by an index. However, if you do need one, you can
224
create it manually and pass it to a page.
225
</p><p>Documents will parse YAML front matter for textual files, unless disabled. The front matter
226
is available as an attribute of the document, and can be accessed using indexing syntax.
227
</p><h4>def <code>__init__(self, file_name: typing.Union[str, bytes, os.PathLike], url_transform: typing.Callable = lambda x: x, front_matter_enabled: bool = True)</code></h4><p>Create a new document. <code>file_name</code> is the name of the file. <code>url_transform</code> is a function
228
that will be applied to the file name to get the new file name; it has the same meaning as
229
in the <code>Index</code>. <code>front_matter_enabled</code> is a boolean that determines whether the document
230
will parse YAML front matter.
231
</p><h4>def <code>__repr__(self)</code></h4><p>Return a string containing <code>Document</code> and the file name.
232
</p><h4>def <code>__getitem__(self, item: str)</code></h4><p>Access the document's front matter. If front matter is disabled or not available, this will
233
never work.
234
</p><h4>def <code>__setitem__(self, item: str, value: typing.Any)</code></h4><p>Change the document's front matter. It works even if it wasn't parsed, because YAML
235
behaves like a dictionary.
236
</p><h4>def <code>__delitem__(self, item: str)</code></h4><p>Delete an item from the document's front matter.
237
</p><h4>def <code>__contains__(self, item: str)</code></h4><p>Check if an item is in the document's front matter.
238
</p>
239
</article>
240
</main>
242
<footer>
243
<p>Page generated on Monday, 29 April 2024 at 09:45:48</p>
244
<p>© Roundabout developer</p>
245
</footer>
246
</body>
247
</html>