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
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 the output 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.

Markdown to HTML (advanced)

Overview #

Ingredients #

Creating the component #

Viash config #

Pandoc config #

Bash script #

Running the component #