document

README

Runtime / Document

Document is a Markdown like format that transpiles TextML to HTML.

Directives

• #metadata take a dictionary of TextML key values represented as a list of #KEY { VALUE } entries. For now this format is under-specified, available values are

  • strings: normal TextML text nodes.

  • dict: #dict{ #KEY_1 { VALUE-1 } ... #KEY-N { VALUE-N } }

• #define{ #NAME{ ARG_1 }...{ ARG_N } }{ EXPRESSION } can be used to encapsulate a repetitive piece of a document.

  For example this can be used to create a "figure" environment with various options.

  #define{
      #figure{
          #src
          #description?
          #placement?
      }
  }{
      <div class="#css.class{ figure $placement }">
          <div class="picture">
              <img src="#{ src }">
          </div>
          #if{ $description }{
              <div class="description">
                  #{ $description }
              </div>
          }
      </div>    
  }
  

  Or for example for charts and graphs...

  #define{
      #graph{
          #expression{ $expr }
          #viewport{ $vp }
      }
  }{
      <div class="graph" data-id="#{ $UUID }"></div>
      <script>
          const id = "#{ $UUID }"
          new Graph(
              document.querySelector(`.graph[data-id="${ id }"]`),
              "#{ $expr }",
              { viewport: "#{ $vp }" }
          );
      </script>
  }
  

• Headings.

  • #title{ TEXT }: <h1>
  • #subtitle{ TEXT }: <h2>
  • #subsubtitle{ TEXT }: <h3>
  • #subsubsubtitle{ TEXT }: <h4>

• Formatting.

  Common:

  • #bold{ TEXT }
  • #italic{ TEXT }
  • #underline{ TEXT }
  • #strikethrough{ TEXT }
  • #code{ TEXT }

  Hyperlinking and interactivity:

  • #link{ TEXT }{ URL }: the mnemonic is "from TEXT to URL".

  • #note{ TEXT }{ NOTE_TEXT }: like a footnote but more generic, wraps TEXT in a span with a random UUID. NOTE_TEXT is put in a <div> at the end of the rendered document with a reference to the generated UUID (something like data-ref-note-id="...")

  • #ref{ TEXT }{ REF }: like previous but only generates the span with a data attribute like data-ref="REF" for interlinking. (This can be used for example for highlighting (with js) all spans with the same REF when one of them is hovered)

  Other:

  • #color{ CSS_COLOR }{ TEXT }: this utility wraps text in a span with the specified color.
  • #mark{ CLASS_NAME }{ TEXT }: this utility wraps text in a span with the specified css class.

• Ordered and Unordered Lists.

  • #itemize{ #item{ TEXT } #item{ TEXT } ... }
  • #enumerate{ #item{ TEXT } #item{ TEXT } ... }

• Images.

  • #image{ URL }

Documentation

Index

• type Engine
  • func (t *Engine) Render(block ast.Block) (Metadata, []html.Node, error)
  • func (t *Engine) RenderBlock(block ast.Block) ([]html.Node, error)
  • func (t *Engine) RenderElement(el *ast.ElementNode) ([]html.Node, error)
• type Metadata

Types

type Engine

type Engine struct{}

Engine is a Markdown like format that transpiles TextML to HTML

func (*Engine) Render

func (t *Engine) Render(block ast.Block) (Metadata, []html.Node, error)

func (*Engine) RenderBlock

func (t *Engine) RenderBlock(block ast.Block) ([]html.Node, error)

func (*Engine) RenderElement

func (t *Engine) RenderElement(el *ast.ElementNode) ([]html.Node, error)

type Metadata

type Metadata map[string]any