Add custom components easily via Markdown

[sc0ttj]

Example:

Writing this:

    ```d3-barchart
    assets/data/some-file.json

would produce markdown output:

```d3-barchart
{[0,1,2],[5,6,7]}
```

which should create final output like:

```html
<div id="d3-barchart-1" data-src="{[0,1,2],[5,6,7]}"></div>
<script defer src="https://unpkg.com/d3"></script>
<script defer src="assets/components/d3-barchart/main.js"></script>

[sc0ttj]

YAML approach

Advantages:

Yaml is dead simple to use - defining charts, embeds, custom elements/components in yml would be nice and easy.

Disadvantages:

Yaml parsers implemented in shell are few and far between, and don't support multi-dimensional arrays or hashes, so they often output the yml data as dynamically named variables - which could get cumbersome/ugly..

Processing the yml data, via mustache templates into JSON might be buggy, slow or incomplete in implementation.

How to

Do something like Jekylls data files...

1. Put a page-name.yml file in assets/data/:

my_cool_line_chart:
  x_axis:
    labels: [2017, 2018, 2019]
  y_axis:
    labels: [0,10,20,30,40,50,60,70,80,90,100]
  data: 
        [
          [34, 45, 67],
          [52, 64, 78],
        ]
cool_bar_chat
  ...

2. Then in your markdown:

Some text.

<?bash
line_chart 'my_cool_line_chart'
?>

More text.

[sc0ttj]

Mustache approach

Disadvantages:

In order to have the required component data (which will most likely begin life as JSON) stored in a way that can be processedby mo (the mustache templater), there is a lot of setup and 'boilerplate' code required .. The original data will need to be transformed into a Bash array of hashes, and multiple nested levels are not possible, so a bit of extra work is required for complex loops in templates..

TLDR: this is a very inefficient way of doing it...

How to

1. create component templates:

File `templates/components//name.{html,js,css,json}.mustache

Example:

• line_chart.json.mustache - a json template for vega line chart data
• line_chart.html.mustache - html for vega chart (container, style and script tag)
• line_chart.js.mustache - init vega with the generated json data
• line_chart.css.mustache - styles

2. Set a var, and use in markdown like so:

line_chart_data=(
  [x1]="2018", 
  [x2]="2019", 
  [y1]="0", 
  [y2]="100", 
  [d1]="23,46,79", 
  [d2]="12,11,19")
line_chart_json="$(render _line_chart 'json')"

in the page/markdown:

Some text.

{{render _line_chart}}

More text.

[sc0ttj]

JSON approach

Advantages:

• no data conversion: most of the frontend libraries that will be used by components (d3, vega, chartjs, chartist, noembed, etc) will require JSON data as input

How to

1. Create the JSON data file in assets/data:

my-cool-line-chart.json ^ contains (for example) a vega line chart config object

2. Create component templates:

File `templates/components/.{html,js,css}.mustache

Example:

vega-line-chart.html.mustache - html for vega chart (container, style and script tag)
vega-line-chart.js.mustache - init vega with the generated json data
vega-line-chart.css.mustache - styles

2. In your markdown:

    ```vega-line-chart
    assets/my-cool-line-chart.json

[sc0ttj]

Outdated