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