Markdown to HTML (advanced)
Overview
This recipe teaches you how to converts a markdown file to HTML using
Viash and Pandoc.
In the simpler version of this
recipe, you used just a Viash config file to
create a component. In contrast, this recipe includes a small script and
a configuration file for Pandoc to format the generated HTML file.
Ingredients
For this recipe, you’ll need:
Creating the component
Viash config
Create a new folder named md2html2 and create a new file named config.vsh.yaml inside of it. Add the following as its content:
functionality:
name: md2html2
arguments:
- name: "input"
type: file
required: true
must_exist: true
description: "Input file"
- name: "--output"
alternatives: [ "-o" ]
type: file
direction: output
required: true
resources:
- type: bash_script
path: script.sh
- type: file
path: config.yaml
platforms:
- type: native
- type: docker
image: pandoc/latex:latest-ubuntu
Here’s a summary:
- A single resource is used, an executable named pandoc.
- This component takes a few arguments:
- input: Path to the markdown file to convert.
- –output: Path where the output file should be saved. You can
use
-o
as an alternative. - –t: The output
format. This is set
to
html5
by default.
- There are two resources used for this component:
- A bash script named
script.sh
- A file named
config.yaml
that’s used to pass style settings to Pandoc
- A bash script named
- This component can be run natively if you have
pandoc
installed. Alternatively, it runs on the Docker platform by using the pandoc/ubuntu-latex image as its base.
Pandoc config
With the Viash config created, it’s time to create the YAML file that contains the defaults, a set of options that will be passed to Pandoc. Create a new file named config.yaml and add this:
from: markdown-auto_identifiers
to: html
toc: false
metadata:
mainfont: Roboto Condensed
monofont: Source Code Pro
monobackgroundcolor: lightgrey
This passes the following options to Pandoc:
- The input is defined as markdown with automatic identifiers
- The output should be html
- There’s no need to generate a table of contents, or TOC
- The main font should be Roboto Condensed, while the mono font used in code blocks is Source Code Pro with a light grey background color.
Bash script
The final piece of the puzzle is a one liner contained in a script to call Pandoc and pass it the defaults file. Create a new file named script.sh and add the following:
pandoc "$par_input" -t html5 -d "$VIASH_RESOURCES_DIR/config.yaml" -o "$par_output" -s --self-contained
Here’s a breakdown:
- The pandoc command gets called with the
input
parameter from the Viash config as its file path using$par_input
. - The
-t
option is used to specify the output type,html5
in this case. - Pandoc gets passed the
defaults
file by using the-d
option.$VIASH_RESOURCES_DIR
points to the folder that contains the resources of the component. - The
-o
option gets passed theoutput
path from the Viash config via the$par_output
variable. -s
makes the html into a standalone valid document, including a HEAD and a BODY tag.- The
--self-contained
flag makes sure no external files are needed and all needed resources are contained in the HTML document.
Running the component
In order to test the component, you’ll need a markdown file. If you don’t have one at the ready, you can create one or download our example file.
To run the component natively, simply call viash run
on the config
file and pass the input and output files as arguments:
viash run md2html/config.vsh.yaml -- md2html2/example.md --output md2html2/output.html
Note: If Pandoc throws an error about a missing
-d
option, that means you have an outdated version of Pandoc installed on your system. You can either download and install the latest version from their repo or use the command below to run it in a Docker container.
In order to run the component as a Docker backend, use the same command
as above and pass the platform
argument to Viash this time:
viash run md2html/config.vsh.yaml -platform docker -- md2html2/example.md --output md2html2/output.html
Viash will generate an executable to call pandoc
and your html file
will be created at the location of your choosing.