From Bike through Pandoc to other formats

Out of the box, Pandoc already does a useful job of translating .bike files directly to formatted MS Word .docx files.

If we start with a Bike file like:

Screenshot 2022-08-09 at 15.43.37

then, with pandoc installed (e.g. with brew install pandoc) the command line:

pandoc -f html -t docx note.bike -o note.docx

creates an MS Word file like:

In which only the highlight formatting ( underlying <marked> tagging) has not been translated automatically.


I haven’t, so far, experimented with customizing pandoc outputs, but it does appear to be possible. The .docx XML markup that we would need to generate, for example, has this kind of pattern:

<w:r w:rsidRPr="00F12617">
    <w:rPr>
        <w:highlight w:val="yellow"/>
    </w:rPr>
    <w:t>marked</w:t>
</w:r>

More generally, pandoc translates bike files to an intermediate (JSON-formatted abstract syntax tree) format which can be represented (and post-processed) in JavaScript or Lua etc. For example,

pandoc -f html -t json note.bike -o note.json

Gives us the JSON representation below which:

  1. preserves the <mark> tagging for the highlight format, and
  2. should allow for transforms like designating the top N levels of an outline as heading levels, etc
Expand disclosure triangle to view Pandoc JSON AST source
{
  "pandoc-api-version": [
    1,
    22,
    2
  ],
  "meta": {},
  "blocks": [
    {
      "t": "BulletList",
      "c": [
        [
          {
            "t": "Div",
            "c": [
              [
                "P9",
                [],
                []
              ],
              [
                {
                  "t": "Para",
                  "c": [
                    {
                      "t": "Str",
                      "c": "Various"
                    },
                    {
                      "t": "Space"
                    },
                    {
                      "t": "Str",
                      "c": "inline"
                    },
                    {
                      "t": "Space"
                    },
                    {
                      "t": "Str",
                      "c": "formats"
                    }
                  ]
                },
                {
                  "t": "BulletList",
                  "c": [
                    [
                      {
                        "t": "Div",
                        "c": [
                          [
                            "vi",
                            [],
                            []
                          ],
                          [
                            {
                              "t": "Para",
                              "c": [
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Str",
                                        "c": "alpha"
                                      },
                                      {
                                        "t": "Space"
                                      }
                                    ]
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Strong",
                                  "c": [
                                    {
                                      "t": "Str",
                                      "c": "bold"
                                    }
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Space"
                                      },
                                      {
                                        "t": "Str",
                                        "c": "etc"
                                      }
                                    ]
                                  ]
                                }
                              ]
                            }
                          ]
                        ]
                      }
                    ],
                    [
                      {
                        "t": "Div",
                        "c": [
                          [
                            "Ru",
                            [],
                            []
                          ],
                          [
                            {
                              "t": "Para",
                              "c": [
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Str",
                                        "c": "beta"
                                      },
                                      {
                                        "t": "Space"
                                      }
                                    ]
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Emph",
                                  "c": [
                                    {
                                      "t": "Str",
                                      "c": "italic"
                                    }
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Space"
                                      },
                                      {
                                        "t": "Str",
                                        "c": "etc"
                                      }
                                    ]
                                  ]
                                }
                              ]
                            }
                          ]
                        ]
                      }
                    ],
                    [
                      {
                        "t": "Div",
                        "c": [
                          [
                            "il",
                            [],
                            []
                          ],
                          [
                            {
                              "t": "Para",
                              "c": [
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Str",
                                        "c": "gamma"
                                      },
                                      {
                                        "t": "Space"
                                      }
                                    ]
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Code",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    "code"
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Space"
                                      },
                                      {
                                        "t": "Str",
                                        "c": "etc"
                                      }
                                    ]
                                  ]
                                }
                              ]
                            }
                          ]
                        ]
                      }
                    ],
                    [
                      {
                        "t": "Div",
                        "c": [
                          [
                            "uA",
                            [],
                            []
                          ],
                          [
                            {
                              "t": "Para",
                              "c": [
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Str",
                                        "c": "delta"
                                      },
                                      {
                                        "t": "Space"
                                      }
                                    ]
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Strikeout",
                                  "c": [
                                    {
                                      "t": "Str",
                                      "c": "strike"
                                    }
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Space"
                                      },
                                      {
                                        "t": "Str",
                                        "c": "etc"
                                      }
                                    ]
                                  ]
                                }
                              ]
                            }
                          ]
                        ]
                      }
                    ],
                    [
                      {
                        "t": "Div",
                        "c": [
                          [
                            "V3",
                            [],
                            []
                          ],
                          [
                            {
                              "t": "Para",
                              "c": [
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Str",
                                        "c": "epsilon"
                                      },
                                      {
                                        "t": "Space"
                                      }
                                    ]
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [
                                        "mark"
                                      ],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Str",
                                        "c": "marked"
                                      }
                                    ]
                                  ]
                                },
                                {
                                  "t": "SoftBreak"
                                },
                                {
                                  "t": "Span",
                                  "c": [
                                    [
                                      "",
                                      [],
                                      []
                                    ],
                                    [
                                      {
                                        "t": "Space"
                                      },
                                      {
                                        "t": "Str",
                                        "c": "etc"
                                      }
                                    ]
                                  ]
                                }
                              ]
                            }
                          ]
                        ]
                      }
                    ],
                    [
                      {
                        "t": "Div",
                        "c": [
                          [
                            "du",
                            [],
                            []
                          ],
                          [
                            {
                              "t": "Para",
                              "c": [
                                {
                                  "t": "Str",
                                  "c": "zeta"
                                },
                                {
                                  "t": "Space"
                                },
                                {
                                  "t": "Str",
                                  "c": "plain"
                                },
                                {
                                  "t": "Space"
                                },
                                {
                                  "t": "Str",
                                  "c": "etc"
                                }
                              ]
                            }
                          ]
                        ]
                      }
                    ]
                  ]
                }
              ]
            ]
          }
        ]
      ]
    }
  ]
}

Thanks for sharing and exploring this. Go HTML format :slight_smile: !

Do let me know if there’s anything I can do to iron out any edge cases on Bike’s side.

1 Like

It does unlock a lot of things …

How to include Bike highlighting in pandoc exports to MS Word docx


Screenshot 2022-08-10 at 18.14.21


  • In addition to the basic pandoc command line for Bike -> MS Word exports:

    • pandoc -f html -t docx note.bike -o note.docx

    • (which already exports Bike's bold , italic code and strike formatting)

  • we can additionally export Bike highlights by adding references – in our command line – to two utility files (reference.docx, and docxHighlight.lua), which can be anywhere on your system.

  • In the command line below we're not giving a full path to either of those files, so we're assuming that they are in the same folder as your .bike file:

    • pandoc -f html -t docx note.bike -o note.docx --reference-doc=reference.docx --lua-filter=docxHighlight.lua

    • The --reference-doc option points to an MS Word file which contains a definition of a custom style called MarkedYellow.

    • The --lua-filter option points to a file containing a snippet of code in the Lua scripting language, to which pandoc provides a special interface.
      This particular snippet maps Bike highlighting onto the custom MarkedYellow style
      in MS Word.

Here are zipped copies of those two files, together with a note.bike file for testing:

bikePandocExample.zip (18.0 KB)


Pandoc itself can be installed with brew install pandoc


Note: If you want to further tweak the appearance of outlines exported from Bike to MSWord by that pandoc command line, you can adjust the existing style definitions in reference.docx


Expand disclosure triangle to view the Lua snippet
function Span(elem)
    if FORMAT:match 'docx' and "mark" == elem.classes[1] then
        elem.attributes['custom-style'] = 'MarkYellow'
    end 
        
    return elem
end
1 Like