Add landing page layout & includes

[Brian Dominick]

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.

• I really like landing pages.
• I need a landing page to promote AsciIDocsy, and it would be weird to use another theme to promote this theme.
• I already have a landing page theme (used here) that I put tens of hours of work into -- not just the front end, either; the config is elaborate.
• A lot of the best documentation themes have halfway-decent landing pages either built (like Docsy) in or at least used to demo/promote their theme.

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:

{% include features.html
  id         = "ops"
  title      = "The Unity Platform"
  desc       = "Bringing technical writers and engineers together."
  nodes      = site.data.features.primary %}

{% include gridfolio.html
  id         = "showoff"
  title      = "For Documentation Worthy of Your Product"
  desc       = "LiquiDoc Ops is JAMstack-based, offering complete front-end freedom.<br/>It also ships with a killer versioning-ready docs theme."
  nodes      = site.data.folio.output.portal %}

{% include quote.html
  id         = "alicia-quote"
  text       = "After searching and testing options for almost a year, I helped design and pilot LiquiDoc Ops. Not only has the LiquiDoc Ops toolchain proven to be a refreshingly nimble and sophisticated way for me to manage our content, but my developer colleagues love working with it."
  attribution= "Alicia Duncan, Lead Technical Writer, <a href='https://www.digi.com/resources/documentation/digidocs/embedded/index.html' target='_new'>Digi International</a>" %}

{% include features.html
  id         = "features-secondary"
  title      = "Enterprise- and Suite-ready"
  desc       = "LiquiDoc Ops is designed for documenting complex products with awkward version-divergence problems by accommodating their necessarily complex sourcing schemes."
  nodes      = site.data.features.secondary %}

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.

primary:

  - name: Free and Open
    text: All components are free/freemium and open standards/FOSS
    icon: folder-open-o
    role: proprietary

  - name: Source Controlled
    text: No binary database, nothing proprietary, everything in Git
    icon: git
    role: proprietary

  - name: Version Aware
    text: Docs and tools that know all your products' permutations
    icon: sort-numeric-desc
    role: markdown

  - name: Enterprise Scale
    text: LiquiDoc Ops means first-class docs across the organization
    icon: industry
    role: markdown

  - name: XML Free!
    text: Lightweight markup means all the power with none of the bloat
    icon: code slash
    role: proprietary

  - name: Writer-friendly Tools
    text: Clide is the unifying CLI utility for command-line phobes
    icon: pencil
    role: markdown

secondary:

  - name: Full Spectrum
    text: Developer docs (including internal) and user-facing docs
    icon: address-card
    role: proprietary,markdown

  - name: Output Anything
    text: Helpsites, manuals (HTML + PDF), JSON, even JS-driven presentations
    icon: file-image-o
    role: proprietary,markdown

  - name: Output Continuously
    text: CI with instant delivery and deployment, for staging and production
    icon: rocket
    role: proprietary

  - name: Frameworked
    text: Libraries, conventions, and utilities for rapid development
    icon: briefcase
    role: markdown,proprietary

  - name: Strategic Divergence
    text: Built-in options for handling edition/version differences
    icon: code-fork
    role: markdown

  - name: RBAC
    text: Roles-based access control, for workspace/UI sanity
    icon: user-times
    role: markdown

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.

[Brian Dominick]

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 %}