commit 13b811029d71b204806fbd89cac3be14eaf3f0af
parent fa1f32f43d17c8fdf45e4ab100eadc1c59e156ed
Author: Byron Torres <torresjrjr@pm.me>
Date: Tue, 30 Jun 2020 18:34:44 +0100
Improve README.md
Diffstat:
| 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.
+
## Requirements
* sh
* pandoc
+
## Installation
-Clone pdssg beside your site source directory
+git clone pdssg, ideally beside your site source directory.
```sh
-$ git clone https://github.com/torresjrjr/pdssg
-$ ls
-src pdssg
+git clone https://github.com/torresjrjr/pdssg
```
+
## Usage
-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.
```sh
+$ 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/` from an exiting, neigboring `src/`
-directory with the site contents (Markdown files to be converted to HTML, and
-other files).
+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
+directory.
```
src/
+|-- _ignore
|-- index.md
|-- about.md
|-- posts.md
+|-- posts/
+| |--- 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
+|-- _includes/
+| |--- header.html
+| |--- footer.html
+| `--- meta.html
+`-- _templates/
+ |--- atom.xml
+ `--- main.html
+```
+
+Here's the resulting build directory.
+
+```
+dst/
+|-- index.md
+|-- about.md
+|-- posts.md
|-- posts/
| |--- 2020-01-01-new-year.md
| |--- 2020-02-01-corona-what.md
| `--- 2020-03-01-stuck-at-home.md
|-- feeds/
| `--- posts.md
-`-- _ignore
+`-- assets/
+ `--- 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
+where appropriate.
[YAML]: https://en.wikipedia.org/wiki/YAML
@@ -79,10 +112,12 @@ date: 2020-12-30
contents...
```
+
### 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.
[Atom]: https://en.wikipedia.org/wiki/Atom_(Web_standard)
[RSS]: https://en.wikipedia.org/wiki/RSS
@@ -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.
---
