Linkmaps

Mapping markdown files to URLs can be extremely tricky, as there are numerous different frameworks and technologies that are used to host and structure markdown files in Github repositories. To combat this, we built and open sourced a quick way to define the "link mappings" for any given repository.

The code itself is a Go package, available on Github.

How Link Mapping Works

When WOPR fetches content from a Github repository, we first check to see if the repository has a linkmap file defined at the root path (can be configured when linking the repository). If it does, we parse that file and use it to map any given markdown file to a URL on the web. This means that, for example, you can easily map markdown files in a /pages directory to any URL on the web, for instance, https://example.com/{page}.

Defining A LinkMap

LinkMap files contain a set of rules, one per line, which define a mapping from a given pattern to another. They are evaluated in order from most complex to least, in an attempt to match the longest possible pattern at every step.

LinkMap files must be named linkmap and sit at the root path of a linked repository.

Consider the following example:

foo/$1.{md,mdx} https://example.com/foo/$1
bar/$1/baz/$2.{md,mdx} https://example.com/$1/$2

In this case,

  • A file located at foo/bar.md (or foo/bar.mdx) will be mapped to https://example.com/foo/bar.
  • A file located at foo/x/baz/y.md (or foo/x/baz/y.mdx) will be mapped to https://example.com/x/y.