Using Pandoc
PureBuilder Simply with Pandoc
PureBuilder Simply uses Pandoc by default, and Pandoc give you to use the very powerful Markdown syntax and template engine.
Although you can use advanced features, installing Pandoc can
be a difficult element in some cases. For this reason,
pbsimply-init
uses a Ruby library (kramdown).
To configure it with Pandoc, a different procedure is required.
Install pandoc
In a Linux environment, you only need to install the package if it is available as a package. For example, in Arch linux, do the following:
$ sudo pacman -S pandoc
It can be used with OpenSUSE in the same way, just by installing the package. OpenSUSE Leap is also useful when using WSL on Windows, since it is available as an image in the Windows Store.
$ sudo zypper in pandoc
Pandoc is called by default with the command
pandoc
. It can be overridden by setting
pandoc_command
in .pbsimply.yaml
.
If you want to use it on Windows, you can install Pandoc on a Linux image on WSL, but in terms of performance, using native Windows Pandoc is superior. You can run Windows executables both from the WSL and from the MSYS2 environment used by Ruby for Windows binaries.
After installing Pandoc on Windows, there are two options.
One is to make the Windows binary be recognized by the
environment as the command pandoc
. For example, as
/usr/local/bin/pandoc
, you can write
#!/bin/bash
exec "/mnt/c/Program Files/Pandoc/pandoc.exe"
The other is to set it up in .pbsimply.yaml
.
pandoc_command: "/mnt/c/Program Files/Pandoc/pandoc.exe"
Create project
First, clone the PureBuilder Simply repository.
git clone https://github.com/reasonset/purebuilder-simply.git
Next, create a project directory at an arbitrary location.
mkdir -pv foo/{Source,Build}
Copy the sample documentation from the repository to the document source root.
rsync -rv purebuilder-simply/docroot-sample/docbase/ foo/Source/
If you are familiar with HTML and CSS, this is a good place to start.
If you want to start with a well-presented page, apply a theme base. For example, if you want to apply the Bloggy theme
rsync -rv purebuilder-simply/docroot-sample/themes/bloggy/ foo/Source/
Template
template.html
is a Pandoc template file. See Pandoc User’s Guide#Templates for
specifications.
Themes that require editing template.html
also
include template.html
.
If you want to set up a template from scratch, you can get a default template by running the following command:
pandoc -D html5
Learn More
The basic usage is the same as in Get started.
If you want to understand and use it more deeply, please read Learn more.