qabex/spmda

Single Page Markdown Application

SPMDA: Single Page Markdown App

Quickstart

$ mkdir spmda-quickstart
$ cd spmda-quickstart

$ npm init from-gh qabex/spmda/basic .
$ gvim index.html docs/*
$ npx qsrv ./docs

Take a look at the qabx/spmda/basic template.

SPMDA Web Components

npx qsrv integration

The "Quick Dev Server" allows live-reloading of changes and auto-updating JSON directory listings. For example, npx qsrv ./docs watches the ./docs directory for changes and keeps "all-docs.json" updated.

The <lsdir-view> web component fetches the specified src json document and then renders all referenced files using other web components such as <markdownit-view>.

The textContent is parsed with JSON5 to be more human-friendly.

...
<script type='module' src='https://cdn.jsdelivr.net/gh/qabex/[email protected]/esm/lsdir-view.mjs'></script>
...
<lsdir-view src='all-docs.json'>
  md: "markdownit-view",
  markdown: "markdownit-view",
  ".vegalite-json": "vegalite-view",
</lsdir-view>
...

Mermaid

The <mermaid-view> web component renders its textContent attribute using the mermaid package.

...
<script type='module' src='https://cdn.jsdelivr.net/gh/qabex/[email protected]/esm/mermaid-view.mjs'></script>
...
<mermaid-view>
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
</mermaid-view>

Vega-Lite

The <vegalite-view> web component renders its textContent attribute using the Vega-Lite package.

The textContent is parsed with JSON5 to be more human-friendly.

...
<script type='module' src='https://cdn.jsdelivr.net/gh/qabex/[email protected]/esm/vegalite-view.mjs'></script>
...
<vegalite-view>
  description: 'A simple bar chart with embedded data.',
  data: {
    values: [
      {a: 'A', b: 28},
      {a: 'B', b: 55},
      {a: 'C', b: 43},
      {a: 'D', b: 91},
      {a: 'E', b: 81},
      {a: 'F', b: 53},
      {a: 'G', b: 19},
      {a: 'H', b: 87},
      {a: 'I', b: 52}
    ]
  },
  mark: 'bar',
  encoding: {
    x: {field: 'a', type: 'ordinal'},
    y: {field: 'b', type: 'quantitative'}
  }
</vegalite-view>

Markdown-It

The <markdownit-view> web component renders its textContent attribute using the markdown-it package and uses highlight-js for code syntax highlighting.

...
<script type='module' src='https://cdn.jsdelivr.net/gh/qabex/[email protected]/esm/markdownit-view.mjs'></script>
...
<markdownit-view>
  # An h1 title
  ### An h3 title
  ...
</markdownit-view>

To facilitate richer markdown-based documentation, block fences starting with ! are delegated into web components. For example:

### First

```!mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

### Second

```!vegalite
description: 'A simple bar chart with embedded data.',
data: {
  values: [
    {a: 'A', b: 28},
    {a: 'B', b: 55},
    {a: 'C', b: 43},
    {a: 'D', b: 91},
    {a: 'E', b: 81},
    {a: 'F', b: 53},
    {a: 'G', b: 19},
    {a: 'H', b: 87},
    {a: 'I', b: 52}
  ]
},
mark: 'bar',
encoding: {
  x: {field: 'a', type: 'ordinal'},
  y: {field: 'b', type: 'quantitative'}
}
```

### Third

becomes:

<h3>First</h3>
<mermaid-view>
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
</mermaid-view>
<h3>Second</h3>
<vegalite-view>
  description: 'A simple bar chart with embedded data.',
  data: {
    values: [
      {a: 'A', b: 28},
      {a: 'B', b: 55},
      {a: 'C', b: 43},
      {a: 'D', b: 91},
      {a: 'E', b: 81},
      {a: 'F', b: 53},
      {a: 'G', b: 19},
      {a: 'H', b: 87},
      {a: 'I', b: 52}
    ]
  },
  mark: 'bar',
  encoding: {
    x: {field: 'a', type: 'ordinal'},
    y: {field: 'b', type: 'quantitative'}
  }
</vegalite-view>
<h3>Third</h3>