This GH Action takes all Markdown documents from a given repository and renders them into HTML documents. The output may be used as a web representation of the repository.
Some repositories rely heavily on text-based content, meaning they have very little source code but a lot of human-readable documents.
Examples of such repositories are my repository notebooks:
Of course, it does not matter what is the ratio of source files to document files — this little tool is useful when it comes to creating websites from Markdown documents already present in the repository.
This GH Action uses Pandoc to render Markdown documents into HTML documents to then be published to e.g. Github Pages.
The main readme.md file (in the root of the repository) is treated as
the landing page of the repository, and thus it is renamed to index.html.
The default Pandoc script converts from markdown to html
with following Pandoc extensions:
- disabled
blank_before_header, - disabled
implicit_figures, - enabled
lists_without_preceding_blankline, - enabled
gfm_auto_identifiers,
thus, the Pandoc --from option is set to
markdown-blank_before_header-implicit_figures+lists_without_preceding_blankline+gfm_auto_identifiers.
This format is pretty close to the GitHub-flavoured Markdown.
The Pandoc built-in gfm format that simulates mentioned flavour was not used,
because it does not allow for LaTeX expressions.
Please refer to the Pandoc manual for further details regarding the program itself.
A table of contents will be generated based on document’s headers of level 2 and higher.
Example:
Given document of contents:
# Document
## Section one
Contents.
## Section two
### Sub-section
Contents.
## Section three
Contents.will result in an output of:
ToC will be inserted after the first level one header (h1 in HTML, # in Markdown),
or after the contents generated from the
YAML metadata block
if it’s present in the document.
As mentioned above the Markdown format we’re using allows for LaTeX expressions to be added to the rendered documents.
By default, LaTeX expressions are rendered using the
Pandoc-KaTeX Rust package.
You can change this behaviour by
providing your own script that calls Pandoc differently.
Use it as a part of your GH Actions workflow:
name: 'render the repository as a website'
uses: 'jerry-sky/vyrow@v0.8.0'The action will create (if it does not already exist) a directory called dist
where you can put your Markdown documents to convert and other files,
that will be simply ignored.
It is advised you should look at use-cases listed below, before implementing it yourself, to better understand how does it work.
Here is an example for how to use this GH Action that will meet
needs of most people that want to publish a website on a root domain,
say website.com.
# This workflow renders all Markdown documents into a HTML website.
name: 'Build the website'
on:
# re-render the website every time new changes are pushed
push:
branches: [master]
jobs:
build:
runs-on: ubuntu-latest
steps:
# checkout the `master` branch
- name: 'Checkout `master`'
uses: actions/checkout@v2.3.4
# prepare the `gh-pages` branch to publish the repository as a website
- name: 'Checkout `gh-pages` into a separate directory'
uses: actions/checkout@v2.3.4
with:
path: 'dist'
ref: 'gh-pages'
# use this action to render all Markdown documents into HTML documents
- name: 'Render the repository as a website'
uses: 'jerry-sky/vyrow@v0.8.0'
with:
# copy all files from the master branch to the `dist` directory
# to make all files visible on the website;
# this option is turned off by default,
# so you can cherry-pick yourself only those files
# that you want to publish
copy-from: '.'
# get current time to mark it in the deployment commit message
- name: 'Get current time'
uses: gerred/current-time@v1.0.0
id: current-time
# deploy the result to the GH Pages branch
- name: push the changes
uses: EndBug/add-and-commit@v7.2.1
with:
message: "deployed on ${{ steps.current-time.outputs.time }}"
branch: 'gh-pages'
cwd: './dist/'
add: '*'
default_author: github_actions
- First, we check out the repository
— the main branch to the current directory and the
gh-pagesone to thedistdirectory. - Then we use VYROW to render out the documents.
- Finally, we commit these changes to the
gh-pagesbranch.
This use-case assumes you have gh-pages branch already created
and GH Pages feature turned on in the settings in your repository.
When dealing with a website that will not be anchored at the root of the domain, you need to specify the website root.
For example, you have a repository on GitHub you want to publish.
The GH Pages website address will be something like
username.github.io/repository.
Then, you have to specify the website-root option
website-root: '/site/'when calling VYROW in your build workflow.
After applying that to the general use-case you will have:
- name: 'Render the repository as a website'
uses: 'jerry-sky/vyrow@v0.8.0'
with:
copy-from: '.'
website-root: '/repository/'in the VYROW section of your workflow.
All parameters of this GH Action are optional.
However, it is encouraged to at least review what options are available
that allow customization of this GH Action.
The directory containing the source Markdown documents that will be converted into output HTML documents.
Default value: dist
You can also attach other files you want to publish alongside the website.
The Bash script that runs Pandoc to convert Markdown documents into HTML documents.
If not provided the default script contained in this repository will be used.
If you want to customize this parameter, you can point it to
a Bash script that runs pandoc with options provided by you.
Please note that your custom script must comply with the switches
list of the default Pandoc script.
The default script accepts following options (switches):
-t— custom Pandoc HTML5 template,-s— custom CSS stylesheet,-h— custom headers file containing additional tags to include in the<head>of all output HTML documents,-d— the working directory,-r— the root of the website.
All options require values to be given.
The -d option is required.
The HTML template to use when converting Markdown documents to HTML documents.
If not provided, the template contained in this repository will be used.
Please refer to the Pandoc Manual for additional details.
Generate a ToC based on document’s level 2+ headings.
Turned on by default.
Set this to 0 to disable this feature.
Add numbering to section headers.
Turned off by default.
Set this to 1 to enable this feature.
CSS stylesheet that is used for displaying output documents.
If not provided, the template contained in this repository will be used.
This is the value that would be used in the <base href="|>here<|">
tag in the <head> of the HTML output document.
However, because the rendered Markdown documents may contain relative
links between them and adding e.g. <base href="/"> would break it.
Thus, we want to apply this behaviour only to global files like
the stylesheet file.
This option should be used if the website is not anchored on the root
of the domain.
For example, you could have the root URL of the website like
https://username.github.io/repository/,
so the website-root parameter should be set to /repository/.
If not provided, then / will be used.
Contents of the provided file will be directly inserted into the
<head> element of all output HTML documents.
If not provided, the template contained in this repository will be used.
Copy all files from given directory to the working directory.
Turned off by default.
This option may be handy in a use-case where you want to publish
the whole repository.
In that case you can set this option to a value of '.' to copy all
files from the checked out master branch to the
working directory.
One can say that this is a glorified GitHub’s Wiki feature. However, I would argue that this way of handling Docs, Wikis, notes or anything of that sort is just another way of doing it, which gives more options, flexibility. This GH Action may be just one tool of many present in one’s website building pipeline.
See LICENSE.md for details about licencing of this GH Action.