WOLFRAM NOTEBOOK

Markdown to Mathematica converter

Introduction

This document proclaims and briefly describes the Raku package "Markdown::Grammar" .
"Markdown::Grammar" has parser grammar suitable for making converters of Markdown files into files of different kind of formats:
◼
  • ✓ Mathematica notebook
    • ◼
  • ○ RMarkdown notebook
    • ◼
  • ○ Jupyter notebook
    • ◼
  • ✓ Pod6 file
    • ◼
  • ○ Org-mode file
    • See the video "Markdown to Mathematica converter (CLI and StackExchange examples)" , [AAv1], for a (quick, 7.5 min) demo.

    Motivation

    Mathematica notebooks

    I am most interested in generating Mathematica notebooks from Markdown.
    I have written a fair amount of Raku-related Markdown documents . Many of those Markdown documents were generated from Mathematica notebooks using M2MD , [JPp1]. But of course, most of the time, further changes and embellishments were made over those Markdown documents. Hence it would be very nice to be able to go back to Mathematica.
    Remark: Raku can be used in Mathematica via the so called RakuMode -- see [AA1].
    Remark: Markdown documents with Raku cells code can be evaluated with Command Line Interface (CLI) scripts of the package "Text::CodeProcessing" , [AAp1]. For more details see the article "Connecting Mathematica and Raku" , [AA1].
    Here is a flowchart that gives better idea of the workflow outlined above:
    Out[]=

    Pod6

    The notebook formats have syntax that makes it hard to evaluate the conversions visually. That is why I use Pod6 -- during development it is much easier to evaluate the Pod6 interpretations produced by the package. (I.e. no need to use another tool to open and evaluate the obtained conversion artifact.)

    Installation

    Raku

    Follow the installation instructions https://rakudo.org .

    Markdown::Grammar

    From Zef ecosystem:
    〉
    zef install Markdown::Grammar
    From GitHub:
    〉
    zef install https://github.com/antononcube/Raku-Markdown-Grammar.git

    Round trip translation

    Consider the following round trip translation experiment:
    1
    .
    Make a Mathematica notebook
    2
    .
    Convert WL notebook into Markdown file with the Mathematica package M2MD
    3
    .
    Convert the obtained Markdown file into Mathematica notebook using the Raku package "Markdown::Grammar"
    4
    .
    Compare the notebooks
    Here is the corresponding flowchart:
    Out[]=

    Related work

    Here is a table of converters from- or to Markdown:
    Remark: Pandoc attempts to be an universal converter, applicable for all couples of formats.
    Remark: Except "this package" there are no other converters from Markdown to Pod6 .
    Remark: In general I like the idea of a Markdown-to-Mathematica converter written in Mathematica. The package "Markdown2WL" attempts that, but unfortunately it is fairly incomplete.

    Command line interface

    The package provides a Command Line Interface (CLI) script, from-markdown . Here is its usage message:
    〉
    > from-markdown --help
    # Usage:
    # from-markdown [-t|--to=<Str>] [-o|--output=<Str>] <file> -- Converts Markdown files into Mathematica notebooks.
    #
    # <file> Input file.
    # -t|--to=<Str> Format to convert to. (One of 'mathematica' or 'pod6'.) [default: 'mathematica']
    # -o|--output=<Str> Output file; if an empty string then the result is printed to stdout. [default: '']
    The CLI script from-markdown takes both file names and (Markdown) text. Here is an usage example for the latter:
    〉
    > from-markdown -to=pod6 'Here is data wrangling code:
    ​
    obj = dfTitanic;
    obj = GroupBy[ obj, #["passengerSex"]& ];
    Echo[Map[ Length, obj], "counts:"]
    ​
    ## References'
    ​
    # =begin
    # =para
    # Here is data wrangling code:
    # =begin code
    # obj = dfTitanic;
    # obj = GroupBy[ obj, #["passengerSex"]& ];
    # Echo[Map[ Length, obj], "counts:"]
    # =end code
    # =begin head2
    # References
    # =end head2
    # =end pod

    Ad hoc notebook generation

    Here is the Command Line Interface (CLI) invocation that generates a notebook expression for a given Markdown text (and prints in the standard output):
    〉
    In[]:=
    cat << EOF | from-markdown '
    ## My section
    Here is some text and a formula $\frac{a}{b}$.
    ​
    Here is a code block:
    ​
    ```python
    1 + 1_000
    ```
    ​
    That is it !'
    EOF
    Alternatively, we can use:
    Remark: Make sure the script from-markdown is accessible in the shell used. It is likely that the command above has to have certain environmental path variables set in order to work. Consider using special shell session, or execute preliminary shell commands like "source ~/.bashrc".

    Acknowledgments

    Many thanks to Jakub (Kuba) Podkalicki for programming the package "M2MD", and helping me to understand a fair amount of Mathematica's low-Level notebook programming .

    References

    Articles

    [FZ1] Faizon Zaman, "Parsing markdown files" , (2021), Community.wolfram.com .

    Guides

    [JG1] John Gruber, Markdown: Syntax .
    [MC1] Matt Cone, Markdown Guide .
    [RC1] Raku Community, Raku Pod6 .

    Packages

    [AAp1] Anton Antonov Text::CodeProcessing Raku package , (2021-2022), GitHub/antononcube .
    [FZp1] Faizon Zaman, Markdown2WL Mathematica package , (2021), GitHub/dishmint .
    [JPp1] Jakub Podkalicki, M2MD , (2018-2022), GitHub/kubaPod .

    Videos

    Wolfram Cloud

    You are using a browser not supported by the Wolfram Cloud

    Supported browsers include recent versions of Chrome, Edge, Firefox and Safari.


    I understand and wish to continue anyway »

    You are using a browser not supported by the Wolfram Cloud. Supported browsers include recent versions of Chrome, Edge, Firefox and Safari.