Markdown to HTML (simple)

Overview

This recipe teaches you how to create a simple wrapper around pandoc using Viash to convert a Markdown file to HTML. This recipe consists solely of of a config file to create the component.

Ingredients

For this recipe, you’ll need:

Creating the component

Config file

Create a new folder named md2html and create a new file named config.vsh.yaml inside of it. Add the following as its content:

functionality:
  name: md2html
  arguments:
    - name: "input"
      type: file
      required: true
      must_exist: true
      description: "Input file"
    - name: "--output"
      alternatives: [ "-o" ]
      type: file
      direction: output
      required: true
    - name: "-t"
      type: string
      required: false
      default: html5
  resources:
    - type: executable
      path: pandoc
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.
  • 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.

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 -- md2html/example.md --output md2html/output.html

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 -- md2html/example.md --output md2html/output.html

After a short while, Viash will generate an executable to call pandoc and your html file will be created at the location of your choosing. The HTML output in this recipe is very basic, without any styling. Check out the slightly more advanced version of this recipe that includes a script and a pandoc configuration file.