Generate a static site and Atom feeds, with Markdown, shell, and pandoc.
git clone pdssg, ideally beside your site source directory.
git clone https://github.com/torresjrjr/pdssg
To run pdssg and build a static site, execute the pdssg script in one directory above the site source directory.
$ ls src/ pdssg/ $ ./pdssg/pdssg
pdssg is a single executable shell script, with no command-line flags. It simply
generates a neighboring site directory
dst/ (destination) from an existing,
src/ (source) with the site's contents (Markdown files to
be converted to HTML webpages, and other files).
pdssg's design is modular and tree-based. Here's an example site source directory.
src/ |-- _ignore |-- _feeds |-- index.md |-- about.md |-- posts.md |-- posts/ | |-- _drafts/ | | `--- 2020-04-01-bored.md | |-- 2020-01-01-new-year.md | |-- 2020-02-01-corona-what.md | `-- 2020-03-01-stuck-at-home.md |-- feeds/ | `-- posts.md |-- assets/ | `-- style.css |-- _templates/ | |-- atom.xml | `-- main.html `-- _includes/ |-- header.html |-- footer.html `-- meta.html
Here's the resulting build directory.
dst/ |-- index.html |-- about.html |-- posts.html |-- posts/ | |--- 2020-01-01-new-year.html | |--- 2020-02-01-corona-what.html | `--- 2020-03-01-stuck-at-home.html |-- feeds/ | `--- posts.html `-- assets/ `--- style.css
Note: files and directories beginning with an underscore
_ will be discarded.
Markdown files will be converted to HTML files, ready as webpages.
The exceptions are filepaths matched by patterns in an
./_ignore file, like a
pdssg expects Markdown files to have a YAML frontmatter block, which is
a block of YAML metadata surrounded by a pair of
---, preceding the rest of
the file contents.
The frontmatter should at least have a
title value, which will be used to make
<h1> title heading.
date values are common, and recommended
Example of a Markdown file:
--- title: My Webpage Title author: John Smith date: 2020-12-30 --- ## Subheading contents...
As in the example, the
_templates directories will be used to
generate the HTML and Atom files. They are then discarded.
For the files in
atom.xmlis used to make HTML documents.
For the files in
meta.htmlis inserted in the document header within the
is inserted in the body within the` tags, before the main content.
is inserted in the body within the` tags, after the main content.
Atom feeds are RSS-like feeds based on a newer, more-robust syndication format. They are essentially used just like RSS and referred to as such. Atom feeds allow readers to subscribe to a website's new content, like a blog.
pdssg can make Atom feeds from directories, with the directory's files as feed entries. To do this, you need to make a specified directory for your feeds, and make an "Atom seed file" as such:
./feeds/) and write it's path in the config file
.mdfile extension to the path (e.g.
Refer to the example site above for demonstration (the
The Atom seed file will be converted to an Atom feed file. This resulting feed
will exist at the new path but with an
.xml extension instead of
this example, the atom feed will appear at
./posts.md file is not necessary for a feed, only a directory.
NOTE: Atom entries are ordered alphanumerically by their corresponding
filenames, not by their
date specified by their YAML frontmatter.
This project was born out of a personal challenge, for my own site. At the request of a friendly blogger, I cleaned it up and made it public.
Contact me: t.me/torresjrjr