pdsite uses the contents of the working directory to generate HTML files. The types of files it takes as input, the location of the output HTML, the HTML theme used, and other site-wide variables are defined via a configuration file (
.pdsite.yml) in the current directory.
pdsite will not run in a directory unless a valid configuration file is present. To quickly create a valid file, use the
$ pdsite init
This will create a default
.pdsite.yml YAML file in your current directory. You can then customize it as desired. Any data defined in the config file is available to the template engine during the build process, so you can use this file to define site-wide variables. For example, the config file used to generate this site looked like:
# pdsite configuration theme: default inputextension: .md outputfolder: .html # Site-wide template variables bootswatch: lumen sitename: "pdsite" pagetitle-suffix: "Pandoc-backed static site generator" footer: '<a class="navbar-link" href="https://github.com/GordStephen/pdsite">GitHub Repo</a> | <a class="navbar-link" href="https://github.com/GordStephen/pdsite/issues">Report an Issue</a>'
Once a config file is defined,
pdsite can convert the current directory into a linked website according to its folder and file structure(hidden files are excluded). For example, this site was generated by the following file structure:
├── CNAME ├── index.md ├── installing.md ├── running.md └── themes ├── choosing-themes.md └── creating-themes.md
In that example, the input directory contains a number of Markdown documents (including some in a subfolder) and a "CNAME" file that needs to be copied in to the output directory.
Converting arbitrarily-deep nested files to HTML is supported, although the built-in themes only support generating navigation menus for up to two levels of folders (e.g.
/category/subcategory/page). A custom theme could support automatically linking to deeper files.
Any (non-hidden) files in the directory structure that aren't recognised as content to be converted (like the "CNAME" file above) are copied over to the output directory without any processing.
To generate the HTML website, just run the
$ pdsite build Creating new build folder... done. Building site... done.
We can check the results in the specified output folder:
$ tree .html .html ├── CNAME ├── index.html ├── installing │ └── index.html ├── running │ └── index.html ├── styles.css └── themes ├── choosing-themes │ └── index.html └── creating-themes └── index.html
The Markdown files have all be converted to HTML, with new directories created where appropriate to allow for simple pretty URLs. Non-Markdown files have been directly copied without any changes (and some new files have also been copied in as part of the theme).
Alternatively, you could use the
serve command, which first builds the site and then launches a server so you can see the results in a browser.
$ pdsite serve Clearing old build folder... done. Building site... done. fix_ug: uid=1000 euid=1000 / gid=1000 egid=1000 / gids: 1000 10 95 http server started ipv6 : yes ssl : no node : localhost.localdomain ipaddr: :: port : 8000 export: /the/current/path/.html user : theuser group : thegroup
localhost:8000 in your browser will display the site output. Auto-regeneration of the site when an input file changes is not yet supported, so you'll need to stop the server and re-run the command to see any modifications.