#169 [Feature Request] Markdown + Interpolated Variables

Open
opened 1 month ago by DaveJarvis · 4 comments

Overview

When writing technical documentation repetition often arises, such as:

  • Application title
  • Company title
  • Directory paths
  • Server names
  • Domain and subdomain names
  • Third-party application names
  • Contact information

Being able to define and render external variables would help make maintaining documentation a little easier.

Feature Request

Create a standard file naming scheme where externally defined variables can be stored, read, interpolated, and substituted within Markdown documents.

Technical

Consider the following files in a repository:

  • README.md
  • definitions.yaml

When someone browses to README.md using the web UI, the following actions take place on the server:

  1. Open definitions.yaml.
  2. Interpolate the variables.
  3. Open README.md.
  4. Apply the interpolated values to all variable references found in README.md.
  5. Render README.md as HTML, with all substituted values in place.

Recursion

Recursion should be limited to a maximum depth of 20 iterations (arbitrary, but should suffice for nearly all purposes).

Delimiters

The ability to define the start and end token delimiters that indicate a variable reference within the Markdown files would be welcome, as hard-coding is an unnecessary restriction. See:

  • {{...}} - Assemble, Handlebars, and others.
  • #{...} - Aaron Parecki
  • $(...) - Jekyll and Julia?
  • ${...} - Bash variables, Apache Camel configuration
  • [%...] - Multimarkdown?
  • $...$ - pandoc variables

Example

The file definitions.yaml in the same directory as README.md contains:

application:
  title: Fireball Dragon Pirate Ninja $application.animal$
  animal: Kit$application.animal.quantity$
    quantity: ten
  url: https://daringfireball.net/

The file README.md contains:

# Introduction
$application.title$ is the greatest application on the planet.
Download the latest version from our [website]($application.url$).

The README.md file is rendered in the browser as:

<h1>Introduction</h1>
<p>
Fireball Dragon Pirate Ninja Kitten is the greatest application on the planet.
Download the latest version from our
<a href="https://daringfireball.net/">w̲e̲b̲s̲i̲t̲e̲</a>.
</p>
# Overview When writing technical documentation repetition often arises, such as: * Application title * Company title * Directory paths * Server names * Domain and subdomain names * Third-party application names * Contact information Being able to define and render external variables would help make maintaining documentation a little easier. # Feature Request Create a standard file naming scheme where externally defined variables can be stored, read, [interpolated](https://en.wikipedia.org/wiki/String_interpolation), and substituted within Markdown documents. # Technical Consider the following files in a repository: * README.md * definitions.yaml When someone browses to `README.md` using the web UI, the following actions take place on the server: 1. Open `definitions.yaml`. 1. [Interpolate](https://dave.autonoma.ca/blog/2019/07/06/typesetting-markdown-part-5/#interpolated) the variables. 1. Open `README.md`. 1. Apply the interpolated values to all variable references found in `README.md`. 1. Render `README.md` as HTML, with all substituted values in place. ## Recursion Recursion should be limited to a maximum depth of 20 iterations (arbitrary, but should suffice for nearly all purposes). ## Delimiters The ability to define the start and end token delimiters that indicate a variable reference within the Markdown files would be welcome, as hard-coding is an unnecessary restriction. See: * `{{...}}` - Assemble, Handlebars, and others. * `#{...}` - Aaron Parecki * `$(...)` - Jekyll and Julia? * `${...}` - Bash variables, Apache Camel configuration * `[%...]` - Multimarkdown? * `$...$` - pandoc variables # Example The file `definitions.yaml` in the same directory as `README.md` contains: ``` yaml application: title: Fireball Dragon Pirate Ninja $application.animal$ animal: Kit$application.animal.quantity$ quantity: ten url: https://daringfireball.net/ ``` The file `README.md` contains: ``` markdown # Introduction $application.title$ is the greatest application on the planet. Download the latest version from our [website]($application.url$). ``` The `README.md` file is rendered in the browser as: ``` html <h1>Introduction</h1> <p> Fireball Dragon Pirate Ninja Kitten is the greatest application on the planet. Download the latest version from our <a href="https://daringfireball.net/">w̲e̲b̲s̲i̲t̲e̲</a>. </p> ```
hw commented 1 month ago
Owner

Interesting idea! This should be a separate tool, tho?

Gitea can embed external renderers (see https://docs.gitea.io/en-us/external-renderers/ for details), so if such a tool exists with a compatible interface it would well be possible to incorporate this ... ;)

Interesting idea! This should be a separate tool, tho? Gitea can embed external renderers (see https://docs.gitea.io/en-us/external-renderers/ for details), so if such a tool exists with a compatible interface it would well be possible to incorporate this ... ;)
DaveJarvis commented 1 month ago
Poster

Interesting idea! This should be a separate tool, tho?

Tangentially, consider the following overview for an editor meant to edit such Markdown documents:

General-purpose Processing

Such editors, such as my Scrivenvar, makes injecting variables into Markdown documents quite easy.

Back to your question.

I also wrote a basic implementation for interpolated variables. It is a separate tool that inputs a YAML file and outputs a YAML file. (Note the command-line options, in particular --regex and --separator.) There's no reason, save elbow grease, a program couldn't be made even more general-purpose to handle various structured input formats to produce various output formats.

Besides being YAML-centric, the main issue I have with the preprocessor is that it is Java-based, rather than written in a language that can produce standalone, cross-platform, static binaries.

A binary could tie into the external renderers.

> Interesting idea! This should be a separate tool, tho? Tangentially, consider the following overview for an editor meant to edit such Markdown documents: ![General-purpose Processing](https://i.imgur.com/8IMpAkN.png) Such editors, such as my [Scrivenvar](https://github.com/DaveJarvis/scrivenvar/), makes injecting variables into Markdown documents quite easy. Back to your question. I also wrote a [basic implementation](https://bitbucket.org/djarvis/yamlp/src/master/README.md) for interpolated variables. It is a separate tool that inputs a YAML file and outputs a YAML file. (Note the command-line options, in particular `--regex` and `--separator`.) There's no reason, save elbow grease, a program couldn't be made even more general-purpose to handle various structured input formats to produce various output formats. Besides being YAML-centric, the main issue I have with the preprocessor is that it is Java-based, rather than written in a language that can produce standalone, cross-platform, static binaries. A binary could tie into the external renderers.
hw commented 1 month ago
Owner

If there is an interesting, powerful and easy-to-use tool we can integrate, we will definitely have a look!

If there is an interesting, powerful and easy-to-use tool we can integrate, we will definitely have a look!
DaveJarvis commented 1 month ago
Poster

If there is an interesting, powerful and easy-to-use tool we can integrate, we will definitely have a look!

There's nothing to perform the variable interpolation (on YAML files) that I know of, besides yamlp. I can't recommend it for server-side because it's written in Java, which gives it some overhead that might not jive with your servers.

The application is simple enough to use if you have Java installed.

> If there is an interesting, powerful and easy-to-use tool we can integrate, we will definitely have a look! There's nothing to perform the variable interpolation (on YAML files) that I know of, besides [yamlp](https://dave.autonoma.ca/blog/2019/07/06/typesetting-markdown-part-5/#yaml-preprocessor). I can't recommend it for server-side because it's written in Java, which gives it some overhead that might not jive with your servers. The application is simple enough to use if you have Java installed.
Sign in to join this conversation.
No Milestone
No Assignees
2 Participants
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
Cancel
Save
There is no content yet.