Markdown to HTML (advanced)
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.
For this recipe, you’ll need:
Creating the component
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
-oas an alternative.
- –t: The output
format. This is set
- There are two resources used for this component:
- A bash script named
- A file named
config.yamlthat’s used to pass style settings to Pandoc
- A bash script named
- This component can be run natively if you have
pandocinstalled. Alternatively, it runs on the Docker platform by using the pandoc/ubuntu-latex image as its base.
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.
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
inputparameter from the Viash config as its file path using
-toption is used to specify the output type,
html5in this case.
- Pandoc gets passed the
defaultsfile by using the
$VIASH_RESOURCES_DIRpoints to the folder that contains the resources of the component.
-ooption gets passed the
outputpath from the Viash config via the
-smakes the html into a standalone valid document, including a HEAD and a BODY tag.
--self-containedflag 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
-doption, 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.