Distill

Destry · 2017-03-27 16:42:25

This is some cool stuff, right here. About page.

It’s a new web framework for publishing research articles, though you can easily imagine the possibilities for any kind of data-driven or longform work.

Article guide.

There are some things in there I could use: authors/affiliations Front Matter, citations/footnotes…

Last edited by Destry (2017-03-27 17:13:43)

Destry · 2017-03-27 17:32:29

Does anyone know how to turn Front Matter like this…

---
authors:
  - Jane Johnson
  - John Janson
affiliations:
  - Jane & Co: https://janedomain.tld
  - John & Bros: https://johndomain.tld
---

Into markup like this…

<ul class="">
  <li>Jane Johnson<sup>1</sup></li>
  <li>John Janson<sup>2</sup></li>
</ul>
<ol class="">
  <li><sup>1</sup> <a href="https://janedomain.tld">Jane & Co.</a></li>
  <li><sup>2</sup> <a href="https://johndomain.tld">John & Bros.</a></li>
</ol>

Via a single script to output it dynamically?

Here’s an example of such output. This doc is just my name, but there will be other docs with multiple authors. As I have it now, the output is manually created in the source file, but if I could manage it in Front Matter, that would make it a lot easier for people scared of HTML.

philwareham · 2017-03-27 18:36:32

You’ll need a Yaml parser at least. There are various implementations available depending on the language (PHP, JavaScript, Ruby, etc).

Bear in mind that front matter is extremely narrow in its scope (mainly intended for meta data or config files). So it may not do all you want in your example above.

Destry · 2017-03-27 18:40:58

Thanks. Good to know. Judging from the “article guide” link I gave above for Distill, it looks like they’ve done exactly that for authors/affiliations. Their referred file is this JavaScript file, which I’m guessing is where the magic is. I’ll have to try and decipher it. I’m not really a JS person, sadly.

Destry · 2017-03-27 18:50:14

That JS file is way over my head. They’ve got so much folded into that, I might as well do brain surgery.

bici · 2017-03-27 20:00:04

Destry wrote #305096:

That JS file is way over my head. They’ve got so much folded into that, I might as well do brain surgery.

Welcome to the Wonderful Wacky World of Google UI. Actually UI is nolonger means User Interface, in google world it stands for Utterly Impossible.

I am getting so sick of all things Google

Destry · 2017-03-28 07:57:26

bici wrote #305097:

I am getting so sick of all things Google

Me too. I’ve been weening off of Google stuff as much as possible.

Anyway, this JavaScript run kit tester for front matter looks useful for anyone who knows anything about JavaScript.

And if anyone can figure out how to do the author/affiliation voodoo, you’ll get your name on the main index page of the glossary with the other global contributors.

That page is still under development, but it will be a wrapping list of names under the main index columns, and contributor names will have a link under them to a respectable website of choice.

Bloke · 2017-03-28 10:42:24

Destry wrote #305101:

if anyone can figure out how to do the author/affiliation voodoo

Can you go low-tech here? It’s Jekyll, right? How about:

---
title: "whatever"
summary: "some content"
authors:
  - name: Jane Johnson
    affiliation: Jane & Co
    url: https://janedomain.tld
  - name: John Janson
    affiliation: John & Bros
    url: https://johndomain.tld
---

{{page.title}}
{{page.summary}}

Blah blah blah blah

Authors:
{% include list.html ref="{{ page.authors }}" %}

And in your list.html file, you can iterate over the object you passed in:

<ul>
    {% assign counter = 1 %}
    {% for item in include.ref %}
        <li>{{ item.name }}<sup>{{ counter }}</sup></li>
        {% assign counter = counter | plus:1 %}
    {% endfor %}
</ul>
<ol class="">
    {% assign counter = 1 %}
    {% for item in include.ref %}
        <li><sup>{{ counter }}</sup><a href="{{ item.url }}">{{ item.affiliation }}</a></li>
        {% assign counter = counter | plus:1 %}
    {% endfor %}
</ol>

Untested, but does that sort of thing work? Then all the end user has to do is know how to add an include statement and pass in the thing they want to list. Less onerous than the full markup, and they’re probably already using {{ }} syntax to get frontmatter content anyway so it’s not much of a stretch.

You could devise a suite of such includes to pacakge up various HTML template output and get hem to just throw suitably-formatted frontmatter at them. The ‘object’ notation using name:value pairs gives you a lot of flexibility.

Destry · 2017-03-29 08:33:17

Thank you, Bloke. What you’re proposing to do, approach it directly with front matter, is exactly what a I wanted to do (not a script like Distill was using).

Unfortunately, it’s not working. I get a “Page build failed” with no additional info. GitHub Pages says under such situations to review this troubleshooting info, but not of that is applicable in my case.

For the most part, you’re front matter construction makes sense to me. But I don’t know enough about it to know if it’s right or wrong. ;) I’ve been wading through the yaml 1.2 spec, but it’s a little dense.

It also lacks explanation of the output “tags”(?) like these: {{content}}, {{counter}}, {{item.foo}}… I don’t need those particular ones explained. I just mean a reference somewhere that defines all the possible options.

As well for all the options for tags like {% include ... %}, {% assign ... %}, {% for ... %}, etc. There seems to be a variety.

Neither can I find any resource about stuff like what you’ve done here: {% assign counter = counter | plus:1 %}, which is where I’m guessing the problem is. Not because it’s wrong, but maybe because Jekyll isn’t recognizing this version? I don’t know.

Jekyll’s documentation kinda of sucks in this respect. It seems to give you a few examples of doing different/basic things but leaves the full scope of what’s possible in the dark. And it’s all scattered around without a single tags reference. (Yeah, Txp!)

I’m guessing the inside spaces around the words are not needed, so I can write them like {{content}} or {{page.foo}} instead of {{ counter }} or {{ page.foo }}?

I don’t want to tie you down with this. I can try and take what you’ve started so far and go to GitHub with it.

Your name still goes on the index!

Destry · 2017-03-29 08:45:19

I should give you some context of where I’m testing…

Here’s my include file, named authors.html:

<section class="contributors">
	<ul class="authors nomark">
    {% assign counter = 1 %}
    {% for item in include.ref %}
        <li>{{item.name}}<sup>{{counter}}</sup></li>
        {% assign counter = counter | plus:1 %}
    {% endfor %}
	</ul>
	<ol class="affiliations nomark">
    {% assign counter = 1 %}
    {% for item in include.ref %}
        <li><sup>{{counter}}</sup><a href="{{item.url}}">{{item.affiliation}}</a></li>
        {% assign counter = counter | plus:1 %}
    {% endfor %}
	</ol>
</section>

Here’s the test front matter:

yaml
contributors:
  - name: Destry Wion
    affiliation: Content Strategy Forum
    url: https://csf.community
  - name: Jan Janson
    affiliation: Jan & Clan
    url: https://janclan.tld

And here’s the output markup:

{% include authors.html ref="{{page.contributors}}" %}

And here’s where it should be showing up: User story

Instead, it’s just rendering the previous version of the markup:

<section class="contributors">
	<ul class="authors nomark">
		<li>Destry Wion<sup>1</sup></li>
	</ul>
	<ol class="affiliations nomark">
		<li><sup>1</sup> <a href="https://csf.community">Content Strategy Forum</a></li>
	</ol>
</section>

Which I guess is because it remembers what worked before the build error and reverts to that as a fail-safe, which is nice, but not the desired result.

Bloke · 2017-03-29 09:17:36

Destry wrote #305119:

What you’re proposing to do, approach it directly with front matter, is exactly what a I wanted to do

Good show. Then it’s just figuring out the details.

I’m far from an expert; never written a line of Liquid in my life until yesterday. What I cobbled together for you was in response to ten minutes spent looking at this guy’s video and learning how to count in Liquid along with a smattering of the Liquid cheat sheet.

{% assign counter = counter | plus:1 %}, which is where I’m guessing the problem is.

Maybe. I don’t know whether GitHub’s implementation of Jekyll is somehow crippled: the resources I looked at yesterday were for “Jekyll” not necessarily “GitHub flavoured Jekyll”. I just — perhaps naively — assumed they’d be the same thing.

I’d have to dive in deeper to be able to help, but for now you should probably do some tests. Go back to basics with a test page containing minimal frontmatter and get it displaying one or two basic fields {{page.something}}. I don’t know if the spaces matter or not, I just put them in for clarity; might be a n00b error on my part.

Then extend that by putting an array of fruits in your frontmatter, like in that guy’s video and see if it works. No includes or anything, just reading it directly from the frontmatter onto an individual page. Then try adding a variable inside the liquid block ({% assign ... %} or an equivalent) and see if it still renders. If that works, try incrementing it by one and see if that works. Then try incrementing it in the for loop and test that. Then try outputting the value of that variable in the loop and see if you get a different value alongside each fruit. Then change parts of it for an object instead of an array, like in that video. Then try putting the whole chunk into an include, and loading it in. And so on.

I wasn’t sure of the syntax for outputting variables directly. It seems that to read variables directly from frontmatter you prefix them with page. and follow it with the frontmatter key name. Maybe you do that for raw Liquid variables as well? I don’t know. Might take some experimenting to see where the limits of this implementation of Jekyll lie.

Destry · 2017-03-29 09:44:23

Bloke wrote #305121:

I don’t know whether GitHub’s implementation of Jekyll is somehow crippled: the resources I looked at yesterday were for “Jekyll” not necessarily “GitHub flavoured Jekyll”. I just — perhaps naively — assumed they’d be the same thing.

They probably are the same, and you’re way ahead of me. I’ll prepare the fruit basket and see what juices out.

Destry · 2017-03-30 12:28:37

I don’t know if I have things fixed or not (guessing not). The build error I get now is routinely:

unable to build page. Please try again later.

There is zero info about this error anywhere online that I’ve been able to find through DDG.

Yesterday I did have a different error about tabs (which can not be used in the front matter to create indents), which lead me to discover this great YAML Lint tool. After running all my front matter through the lint cleaner, it corrected your lines here:

yaml
authors:
  - name: 
    affiliation: 
    url: 
  - name: 
    affiliation: 
    url:

To this:

yaml
authors:
  - 
    name: 
    affiliation: 
    url: 
  - 
    name: 
    affiliation: 
    url:

I also learned from the lint cleaning that quotes are needed around all strings of two or more words, as well as any URIs, for example:

yaml
summary: "Yipes! Summary needed"

collaborators:
  - 
    who: "First Last"
    affiliation: "Entity Name"
    affiliation_url: "https://content-strategy-forum.github.io/csf-glossary/{{ page.title | slugify }}.html"

I also made a lot of various changes to my markup as I found better ways of serializing things. The idea being to remove as much markup out of the way as possible. (Though I’m beginning to see a compromise point.)

For example, handling figures (only 1 per definition allowed), I’m hoping I can put the figure code in an include, create a single figure object in front matter, and use a conditional to add it all if there’s figure data…

Front matter:

yaml
figure: 
  - 
    fig_slug: placeholder
    fig_alt: "A placeholder. Huzza!"
    fig_caption: "A belle figure of mysterious nature."

Markup:

{% if ref="{{ page.figure }} %}
    {% include figure.html %}
{% endif %}

The figure.html Include:

<figure>
	<img alt="{{ item.fig_alt }}" src="{{ site.github.url }}/assets/images/{{ item.fig_slug }}.png">
	<figcaption>
		{{ item.fig_caption }}
	</figcaption>
</figure>

It seems to me that would work, but it’s still unverified.

I like the idea of treating the figure front matter as a single object instead of 3 separate variable strings, though I guess it doesn’t matter. It just looks better in the front matter; you easily see the association.

But… I’m at a loss about this current error which I’ve had since yesterday. No clue what to do at this point.

I was hoping not to have to install Jekyll locally, but the more I learn about using front matter to parse much of the content (touchiness with indent construction, quotes, and whatever else I’ve yet to learn), the less certain I am about it’s human-friendliness when low-tech folks start poking in things. I don’t want to end up being a full-time build troubleshooter on this project. At least with HTML it’s easy to see where the problem is. No hidden voodoo and cryptic error messages.

Destry · 2017-03-30 14:23:44

Hmm… looks like the figure yaml I’m conceiving is better suited to a hash, not a sequence:

yaml
figure: 
  fig_slug: placeholder 
  fig_alt: "A placeholder. Huzza!"
  fig_caption: "A belle figure of mysterious nature."

Now, how to figure out the Liquid for that… That’s the challenge I’m having right now, getting my head around using Liquid under different objectives.

Also, it appears your authors/affiliations sequence (list array?) should have been fine, Bloke, looking at this, so I don’t know what’s up with that Lint tool, in fact.

Destry · 2017-03-30 15:16:41

According the Array or hash access info there, I should be able to grab a hash key value by using variable[key]. That’s the bit I’ve been trying to figure out.

If I understand that correctly, then…

1) I could have the figure YAML structured like this:

yaml
figure:
  fig_slug: placeholder 
  fig_alt: "A placeholder. Huzza!"
  fig_caption: "A belle figure of mysterious nature."

Use an include that references the variable like this:

{% if ref="{{ page.figure }} %}{% include figure.html %}{% endif %}

Then grab each variable key like this in the include markup:

<figure>
  <img alt="{{ page.figure[fig_alt] }}" src="{{ site.github.url }}/assets/images/{{ page.figure[fig_slug] }}.png">
  <figcaption>{{ page.figure[fig_caption] }}</figcaption>
</figure>

I hope it works like that, because that would be useful for lots of other things.

Textpattern CMS

Textpattern CMS support forum

#1 2017-03-27 16:42:25

Distill

#2 2017-03-27 17:32:29

Re: Distill

#3 2017-03-27 18:36:32

Re: Distill

#4 2017-03-27 18:40:58

Re: Distill

#5 2017-03-27 18:50:14

Re: Distill

#6 2017-03-27 20:00:04

Re: Distill

Destry wrote #305096:

#7 2017-03-28 07:57:26

Re: Distill

bici wrote #305097:

#8 2017-03-28 10:42:24

Re: Distill

Destry wrote #305101:

#9 2017-03-29 08:33:17

Re: Distill

#10 2017-03-29 08:45:19

Re: Distill

#11 2017-03-29 09:17:36

Re: Distill

Destry wrote #305119:

#12 2017-03-29 09:44:23

Re: Distill

Bloke wrote #305121:

#13 2017-03-30 12:28:37

Re: Distill

#14 2017-03-30 14:23:44

Re: Distill

#15 2017-03-30 15:16:41

Re: Distill

Board footer