Use some form of configuration for page-building

[oubiwann]

For example, we could use lfe config files to set up pages like slate does for its one-pagers. We could also support the Jekyll-type of metadata at the beginning of Markdown files.

Regardless, we should be able to combine any of the following to easily form a single page:

• allow .md files
• allow html fragments
• allow a module name (function to be determined by behaviour definition)

Part of epic lfe/docs#69

[oubiwann]

To support synatx highlighting for blocks of markdown, we would need to:

1. identify the block
2. determine the source type (e.g. the language post-fix at the start of the block)
3. extract the block body
4. run in through a syntax highlighter
5. return the HTML

This could be done with either the following oldie-but-goodie or something like it:

• https://sourceforge.net/p/syntaxhighlight/code/HEAD/tree/highlight/langDefs/

Then, there's the JS approach where we could use this:

• https://github.com/isagalaev/highlight.js/
• https://highlightjs.org/static/demo/

I guess it's more modern to go with the latter approach ;-) Will need to figure out how it works:

• http://highlightjs.readthedocs.org/en/latest/api.html

[oubiwann]

Been trying to figure out the best way to support single-page template assignment/metadata annotation. Right now, the LFE docs use Jekyll's approach there the top of the file is interpreted as containing metadata if it has a couple of breaks. This metadata section is rendered as a table by Markdown parses that aren't converting it to HTML (you can see examples of this when browsing the .md files in the LFE docs).

I'm thinking of maybe using a code block instead ... and putting LFE in it, a la lcfg (and, in fact, the way the rest of the configuration is being done for this project). So there could be a rule like "if the first line of the file starts a codeblock, and the lang type is dragon-metadata, then parse it, augment the conrfiguration with the metadata just parsed, discard the parsed metadata (i.e., don't include it in the output), and process the rest of the file as markdown.

This would allow us to more-or-less keep the same structure we have for files right now -- we'd just have to update the metadata blocks. That takes care of .md files ...

We could also offer something similar to what Slate does: a configuration file that lists "includes" that are to be added (in order). So for complicated pages that are composed of content from multiple sources (and sources of different types, local, and remote), we could offer a mechanism.

.html files could be copied as-is.

Everything else could be skipped ...

This would mean that we could walk a source directory, parse supported files, and thus generate a site in a manner very similar to what we do now with Jekyll.

I still need to give more thought to what we do with things like:

• Collections of loose .md files from other repos
• .md files from other reopse that form part of an integrated whole (e.g., Gitbook projects)

I think there are other cases, too ... can't think of them right now.

Anyway, whatever solution is arrived at should be applicable across a majority of the use cases our users/readers care about ...

[oubiwann]

The way the new static site generation is working (using the poise library), content generation and any related data sources are completely open-ended. As we start to pull in content from other places (or data used to build content) we can define some generally useful functions for those data sources, and that will be pretty much it. Super-flexible, no brain-strain.

As such, I consider this ticket done :-)