Taitan is a RESTful markdown to HTML supplier of pages for bawang and styrdokument-bawang.

Taitan(タイタン) is romaji for Titan.

Retrieve a markdown document.

GET /:path

An example response to GET /om-oss could look like this:

{
  "title": "Om Oss",
  "slug": "om-oss",
  "url": "/om-oss",
  "updated_at": "2022-11-06T02:04:58Z",
  "image": "https://example.com/static/hej.png",
  "message": "hej",
  "body": "<h1>...",
  "sidebar": "<ul>...",
  "sort": 1,
  "expanded": false,
  "anchors": [
    {"id": "id", "value": "asdf", "level": 1},
    {"id": "foo-baz", "value": "foo baz", "level": 2}
  ],
  "nav": [
    {
      "slug": "/faq",
      "title": "FAQ",
      "sort": 2
    },
    {
      "slug": "/foo",
      "title": "joke",
      "sort": 3,
      "expanded": true,
      "nav": [{
        "slug": "/foo/bar",
        "title": "baz",
        "sort": null
      }]
    },
    {
      "slug": "/om-oss",
      "title": "Om Oss",
      "sort": 1,
      "active": true
    }
  ]
}

Some notable behaviours:

• A nav item with expanded set to true is equivalent to that item containing a nested nav.
• If the main url parameter is a nested path, that path will always appear in the nav-tree with active set to true, and with all its ancestor nav-nodes having expanded set to true.
• anchors will contain a list of all heading tags in the page, with level indicating weather it is a <h1>, <h2>, <h3>, etc.

If you have docker installed, you can also run the repo using docker compose up --build

Make sure to copy .env.example to .env first, and populate TOKEN with you personal github token if needed (if your content repo is private).

Note that CONTENT_DIR will not work with the current compose.yml file.

Requires: golang, git

Minimal setup:

1. Run go mod vendor
2. Set relevant env-variables
3. run go run .

taitan has two webhooks intended to keep it's content updated.

• Any request with the header X-Github-Event set to push will cause taitan to refetch the content-repo. Meant to be called from a workflow in the content repo that is run on new commits.
• Any request with the header X-Darkmode-Event set to updated will cause taitan to refetch the darkmode status from DARKMODE_URL.

Taitan uses path-based routing. I.e. if your content repo contains a directory foo with a subdirectory bar, you will get the content of that subdir by navigating to <taitan url>/foo/bar.

Every directory has to contain a meta.toml, a sidebar.md and a body.md file, the content of which are described below.

Directories starting with a . is ignored by taitan. (eg. .github).

The purpose of this file is to provide meta-data that the frontend might or might not need to render a page.

The meta.toml files can contain the following fields:

A markdown file that will contain content intended to render as a sidebar for a route.

This is the file that will contain the html content that will be served for a route. It is written in markdown, and the generated page will be very similar to how the markdown is rendered.

taitan has support for hiding some content during reception mode by surrounding text with {{ if .reception -}} {{- else -}} {{- end }} .

some text

{{ if .reception -}}
  nothing to see here :)
{{- else -}}
  secret text
{{- end }}

more text

When DARMODE_URL returns true (during reception), this will render as:

some text

nothing to see here :)

more text

If it returns false (the rest of the year), it will render as:

some text

secret text

more text

I hereby release this code into the public domain.