pdssg

Pandoc static site generator
git clone https://git.torresjrjr.com/pdssg.git
Log | Files | Refs | README | LICENSE

README.md (4739B)


      1 # pdssg - pandoc static site generator
      2 
      3 Generate a static site and Atom feeds, with Markdown, shell, and pandoc.
      4 
      5 
      6 ## Requirements
      7 
      8 *	sh
      9 *	pandoc
     10 
     11 
     12 ## Installation
     13 
     14 git clone pdssg, ideally beside your site source directory.
     15 
     16 ```sh
     17 git clone https://github.com/torresjrjr/pdssg
     18 ```
     19 
     20 
     21 ## Usage
     22 
     23 To run pdssg and build a static site, execute the pdssg script in one directory
     24 above the site source directory.
     25 
     26 ```sh
     27 $ ls
     28 src/  pdssg/
     29 $ ./pdssg/pdssg
     30 ```
     31 
     32 pdssg is a single executable shell script, with no command-line flags. It simply
     33 generates a neighboring site directory `dst/` (destination) from an existing,
     34 neigboring directory `src/` (source) with the site's contents (Markdown files to
     35 be converted to HTML webpages, and other files).
     36 
     37 pdssg's design is modular and tree-based. Here's an **example site** source
     38 directory.
     39 
     40 ```
     41 src/
     42 |-- _ignore
     43 |-- _feeds
     44 |-- index.md
     45 |-- about.md
     46 |-- posts.md
     47 |-- posts/
     48 |   |-- _drafts/
     49 |   |   `--- 2020-04-01-bored.md
     50 |   |-- 2020-01-01-new-year.md
     51 |   |-- 2020-02-01-corona-what.md
     52 |   `-- 2020-03-01-stuck-at-home.md
     53 |-- feeds/
     54 |   `-- posts.md
     55 |-- assets/
     56 |   `-- style.css
     57 |-- _templates/
     58 |   |-- atom.xml
     59 |   `-- main.html
     60 `-- _includes/
     61     |-- header.html
     62     |-- footer.html
     63     `-- meta.html
     64 ```
     65 
     66 Here's the resulting build directory.
     67 
     68 ```
     69 dst/
     70 |-- index.html
     71 |-- about.html
     72 |-- posts.html
     73 |-- posts/
     74 |   |--- 2020-01-01-new-year.html
     75 |   |--- 2020-02-01-corona-what.html
     76 |   `--- 2020-03-01-stuck-at-home.html
     77 |-- feeds/
     78 |   `--- posts.html
     79 `-- assets/
     80     `--- style.css
     81 ```
     82 
     83 Note: files and directories beginning with an underscore `_` will be discarded.
     84 
     85 
     86 ### Webpages and Markdown
     87 
     88 [Markdown][Markdown] files will be converted to HTML files, ready as webpages.
     89 The exceptions are filepaths matched by patterns in an `./_ignore` file, like a
     90 `.gitignore` file.
     91 
     92   [Markdown]: https://en.wikipedia.org/wiki/Markdown
     93 
     94 pdssg expects Markdown files to have a [YAML][YAML] frontmatter block, which is
     95 a block of YAML metadata surrounded by a pair of `---`, preceding the rest of
     96 the file contents.
     97 
     98 The frontmatter _should_ at least have a `title` value, which will be used to make
     99 a `<h1>` title heading. `author` and `date` values are common, and recommended
    100 where appropriate.
    101 
    102   [YAML]: https://en.wikipedia.org/wiki/YAML
    103 
    104 Example of a Markdown file:
    105 
    106 ```markdown
    107 ---
    108 title:  My Webpage Title
    109 author: John Smith
    110 date:   2020-12-30
    111 ---
    112 
    113 ## Subheading
    114 
    115 contents...
    116 ```
    117 
    118 ### Templates and Includes
    119 
    120 As in the example, the `_includes` and `_templates` directories will be used to
    121 generate the HTML and Atom files. They are then discarded.
    122 
    123 For the files in `_templates`:
    124 
    125 *	`atom.xml`  is used to make HTML documents.
    126 *	`main.html` is used to make Atom feeds.
    127 
    128 For the files in `_includes`:
    129 
    130 *	`meta.html`   is inserted in the document header within the `<meta>` tags.
    131 *	`header.html` is inserted in the body within the `<body>` tags, before
    132 	the main content.
    133 *	`footer.html` is inserted in the body within the `<body>` tags, after
    134 	the main content.
    135 
    136 
    137 ### Atom feeds
    138 
    139 [Atom][Atom] feeds are RSS-like feeds based on a newer, more-robust syndication
    140 format. They are essentially used just like [RSS][RSS] and referred to as such.
    141 Atom feeds allow readers to subscribe to a website's new content, like a blog.
    142 
    143   [Atom]: https://en.wikipedia.org/wiki/Atom_(Web_standard)
    144   [RSS]: https://en.wikipedia.org/wiki/RSS
    145 
    146 pdssg can make Atom feeds from directories, with the directory's files as feed
    147 entries. To do this, you need to make a specified directory for your feeds, and
    148 make an "Atom seed file" as such:
    149 
    150 1.	Create a feeds directory (e.g. `./feeds/`) and write it's path in the config
    151 	file `_feeds`
    152 2.	Note the path of a directory you want to make a feed (e.g. `./posts/`).
    153 3.	Prepend your feeds directory path to it (e.g. `./feeds/posts/`).
    154 4.	Append the `.md` file extension to the path (e.g. `./feeds/posts.md`).
    155 5.	Create a Markdown file with this path. This is the Atom seed file.
    156 6.	Write a YAML frontmatter to the file.
    157 
    158 Refer to the **example site** above for demonstration (the `posts/` directory).
    159 
    160 The Atom seed file will be converted to an Atom feed file. This resulting feed
    161 will exist at the new path but with an `.xml` extension instead of `.md`. In
    162 this example, the atom feed will appear at `example.com/feeds/posts.xml`. Note,
    163 the `./posts.md` file is not necessary for a feed, only a directory.
    164 
    165 **NOTE:** Atom entries are ordered alphanumerically by their corresponding
    166 filenames, not by their `date` specified by their YAML frontmatter.
    167 
    168 ---
    169 
    170 ## Author's notes
    171 
    172 This project was born out of a personal challenge, for my own site. At the
    173 request of a friendly blogger, I cleaned it up and made it public.
    174 
    175 Contact me: [t.me/torresjrjr](https://t.me/torresjrjr)
    176