Author: Byron Torres <firstname.lastname@example.org>
Date: Tue, 30 Jun 2020 18:34:44 +0100
|M||README.md|| | ||67||++++++++++++++++++++++++++++++++++++++++++++++++++++---------------|
1 file changed, 52 insertions(+), 15 deletions(-)
diff --git a/README.md b/README.md
@@ -2,52 +2,84 @@
Generate a static site and Atom feeds, with Markdown, shell, and pandoc.
-Clone pdssg beside your site source directory
+git clone pdssg, ideally beside your site source directory.
-$ git clone https://github.com/torresjrjr/pdssg
+git clone https://github.com/torresjrjr/pdssg
-To run pdssg and build a static site:
+To run pdssg and build a static site, execute the pdssg script in one directory
+above the site source directory.
pdssg is a single executable shell script, with no command-line flags. It simply
-generates a neighboring site directory `dst/` from an exiting, neigboring `src/`
-directory with the site contents (Markdown files to be converted to HTML, and
+generates a neighboring site directory `dst/` (destination) from an existing,
+neigboring directory `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**.
+pdssg's design is modular and tree-based. Here's an **example site** source
+| |--- 2020-01-01-new-year.md
+| |--- 2020-02-01-corona-what.md
+| `--- 2020-03-01-stuck-at-home.md
+| `--- posts.md
| `--- style.css
+| |--- header.html
+| |--- footer.html
+| `--- meta.html
+ |--- atom.xml
+ `--- main.html
+Here's the resulting build directory.
| |--- 2020-01-01-new-year.md
| |--- 2020-02-01-corona-what.md
| `--- 2020-03-01-stuck-at-home.md
| `--- posts.md
+ `--- style.css
+Note: files and directories beginning with an underscore `_` will not be added.
### Webpages and Markdown
[Markdown][Markdown] files will be converted to HTML files, ready as webpages.
@@ -60,8 +92,9 @@ pdssg expects Markdown files to have a [YAML][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
-a `<h1>` heading. `author` and `date` values are recommended when appropriate.
+The frontmatter _should_ at least have a `title` value, which will be used to make
+a `<h1>` title heading. `author` and `date` values are common, and recommended
@@ -79,10 +112,12 @@ date: 2020-12-30
### Atom feeds
[Atom][Atom] feeds are RSS-like feeds based on a newer, more-robust syndication
format. They are essentially used just like [RSS][RSS] and referred to as such.
+Atom feeds allow readers to subscribe to a website's new content, like a blog.
@@ -96,13 +131,15 @@ entries. To do this, make an "Atom seed file" as such:
4. Create a Markdown file with the path.
5. Write a YAML frontmatter to the file.
-Refer to the **example site** above (the `posts/` directory).
+Refer to the **example site** above for demonstration (the `posts/` directory).
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. In this example, the
-atom feed will appear at `example.com/feeds/posts.xml`.
+atom feed will appear at `example.com/feeds/posts.xml`. Note, the `post.md` file
+is not necessary for a feed, only a directory.
-**NOTE:** File entries are ordered alphanumerically by their filenames.
+**NOTE:** Atom entries are ordered alphanumerically by their corresponding
+filenames, not by their `date` specified by their YAML frontmatter.