Open briandominick opened 3 years ago
I'm going to add the template I use to convert YAML into the Liquid include statements in the first listing, just for anyone who might find this interesting and want to implement it. This Liquid template will save lots of headache.
{% for sctn in data.sections %}
{% raw %}{% include{% endraw %} {{ sctn[1].file }}
id = "{{ sctn[0] }}"
{% for arg in sctn[1].properties -%}
{%- if arg[1].first %}
{{ arg[0] }} = true
{%- for a in arg[1] %}
{{ arg[0] }}_{{ a[0] }} = "{{ a[1] }}"
{% endfor -%}
{%- else -%}
{{ arg[0] }} = "{{ arg[1] }}"
{% endif -%}
{%- endfor -%}
{%- if sctn[1].nodes %}
nodes = {{ sctn[1].nodes }}
{% endif -%}
{% raw %}%}{% endraw %}
{% endfor %}
I've never had a client ask me for a landing page as part of a documentation theme. Nevertheless, there are a few reasons I want AsciiDocsy to include a robust landing-page capacity.
The landing page theme I've already made for one case (but not yet generalized or open-sourced) is not done mainly with AsciiDoc. In fact, the only AsciiDoc at all is inside strings of text, which are nearly all stored in YAML objects that define the sections.
Here is some sample markdown driving that site.
The first thing that I did was create templates (or convert, from Agency and Airspace themes) for the different segments. These templates required lots of arguments when included, so I created elaborate includes like the following:
Each of these blocks of code of course calls a file that embeds the content inside HTML directly. That works pretty well, mind you, but honestly Liquid is the LAST of all the markups I use that I actually want to write content in. Liquid is really not for content -- especially not its
{% include %}
tagging process. Ew.That's why I came up with a YAML-driven solution. Here i an example of the source of content that populated some of these includes.
I have not seen anyone else do this, so it might be a terrible idea, but I found it really rewarding.
Now, much as I prefer authoring in YAML over Liquid, my favorite format for authoring is of course AsciiDoc. The problem is, however, that just as Markdown does not make great sense for technical authoring, AsciiDoc does not make a great source for landing pages.
The truth is almost certainly that no single content markup format is or could ever be ideal for a landing page. But even the semantics of AsciiDoc are all off, so we'd almost be better off creating a dreaded domain-specific language (DSL) for landing pages. Well, for me, that just means using YAML with some semantic intent, which is what I've done here.
The landing page currently in use here is actually my second attempt to create a landing-page layout/theme that could be driven by AsciIDoc only, with optional PDF output (because why not?), perhaps with very small snippets of passthrough (verbatim) HTML code, for stuff that wouldn't work good in PDF anyway and could thus be conditioned out. I am ready to call this second earnest attempt a failure. I have considered creating a different set of AsciiDoc conversion templates, but that feels like pouring lots more work into an idea that just isn't good enough to warrant the effort.
So I think I'm going to introduce my novel Landing page method and the basic theme that makes it work, right here inside AsciiDocsy. It should work independently of the rest of the theme, in fact, so you could use it for just a landing page, as I have.