Metadata for Markdown YAML

Scrivener
,
1

Typically, markdown documents are expected to (or allowed to) have metadata at the top, in YAML format, such as:

Date: 2018-07-09 Title: "My Document Title" Blurb: "Some vague description of the article"

I’m toying with using Scrivener to generate articles into my web site, which expects Markdown files, with YAML I need to specify. I’m having great difficulty discovering where this is specified in Scrivener and how to control its format. Searching the manual for “metadata” does not seem to be the way, so perhaps someone could offer me an outline and/or some links.

I’ve turned on the metadata checkbox in the Compile Format Section Layouts, and indeed it starts coming out. System-provided metadata seems to be tabbed in:

Created: June 28, 2018 at 3:41 PM Modified: June 30, 2018 at 10:01 AM Status: No Status Label: No Label

When I provide a custom item using the little tag thing in a document, that item appears but is not tabbed in.

How can I get them all NOT to be tabbed in, since I pretty much want metadata left justified? And where are those standard items defined, so that I can add in the ones I want and remove the ones I don’t.

Secondly, I need a metadata line “Categories:” which will be a list, but not of fixed elements but elements that I provide on the fly, as needed, in specific documents. How might this best be done?

Certainly if there’s a nice self-contained writeup of this already, please point me to it, and tell me how I might have found it on my own.

Thanks!

2

There may not be a write-up yet, or at least one that is modern. I know I’ve shared similar tips long ago, but aimed at the v2 compile engine, where this kind of thing could be done, but only by kludging data into the Title Suffix field.

The Metadata checkbox in the Section Layout pane that you are referring to is not specifically a reference to Markdown metadata—it’s a feature that is available to everything from ePub to PDF to HTML, and simply a basic and one-step way to export internal information about each section of the binder. For Markdown, uses a “code block” to preserve the formatting of the metadata.

Every single thing that this checkbox does can be replicated using the placeholders found in the Help ▸ List of All Placeholders… command. In combination with a Layout tool such as the section Prefix tab, one could easily design their own metadata template, to whatever specification they desired (YAML, XML, HTML meta elements, etc.), using only the keys they are interested in having printed.

That sounds exactly like the Keywords feature to me. Again with the above, since you have full control over how the keyword list is presented, you can call it “Categories” or whatever you want:

Categories:\t<$keywords>
3

Hm, and um. I take it “Code block” explains why there’s a tab in front of the built-in items? I’m not sure whether that’s Kosher or not but I can try to compile it and see if Jekyll objects.

But my custom item doesn’t get a tab in front. How might I best adjust that?

And my hope had been that compiling the metadata in, at the right level, could auto-insert it into sections that are going to be broken out (with my splitter based somewhat on yours).

To get that to work, ideally, I could cause Scrivener not to show (or just delete) some built-in items, rename others, include placeholders in others (like title:, where I’d include the document title (not project title), and so on.

Pointers and hints welcome. Otherwise I’ll just keep searching and trying until I succeed or give up. Neither is quite what one hopes for. :slight_smile:

4

Indeed, it looks like there is a bug there in the output of custom metadata fields. Thanks for pointing that out!

As for the remainder of your question, I’m confused as to how the method I described in the previous post does not provide all of the flexibility you are looking for.

5

Web site is folders full of subfolders each with an article index.html, with the folder name reflecting the article title. This means that ronjeffries.com/articles/how-to-scriv/ can be the URL for an article with index.html implied.

Idea is to use Scrivener to create some subset of these, probably with Scriv folders for upper level folders. documents for each article, each intended to be in its own folder. Then at compile time, a “splitter” program would run on the Scriv output, split out the articles, create folders with munged title names, write the document to index.html in the folder.

Each article, of course, requires its own YAML. One way would be just to type it in, and it may come to that. Another, perhaps more useful, is to generate it in splitter, based on document title and hints in the text, which could again be hand-crafted. Another, which I was exploring, was to set things up in Scriv’s metadata and compile it in.

(My approach to Scrivener has this pattern, where I try to apply its notions like metadata and synopsis and such to compiling to final documents. That approach has been fraught, but I am a man full of hope. So I do see that I can hand-craft metadata into each document, and I was looking for something a bit more automatic. And … it’d be nice to be able to compile one way to create my site, and another way to have the Scrivener-written part be a book or something. Yes, two layouts would do that. Not as easy as one might have wished is all.)

So what would be “nice” would be a canned solution oh here’s how one does this in Scrivener. What would be more likely would be to get enough of an understanding of how Scrivener goes from its various metadata things to what goes into the heading of a document when the box is checked. Most likely although least leverage is to suck it up and just type in the YAML, using Scrivener as a convenient repo for articles and little else.

For best results in a tricky usage like this, one needs to understand Scrivener’s behavior pretty well, specifically like how to get one’s own tags to go in to the document (apparently buggy) and how to remove some of Scrivener’s (though extra YAML is generally harmless and I should get over it).

So is there enough more to learn to be better able to automate this kind of split-out … or shall I just bite the bullet and do manual YAML in each document?

6

Well sure, but like I said the checkbox you are referring to is for cases where configuration of the output is less important than having all of the raw data present—think backups and proofing. I’d forget it, it’s not the right tool for what you are looking to do.

I’ve read your post several times, and I don’t see an explanation for why the method I described does not already do exactly what you are looking for. If you could give me an example for where it falls short, I could give it some thought and maybe come up with a solution.

There are a number of ways one could go about doing this, if the specific mechanism I described is inappropriate (perhaps you need section types to perform multiple mutually exclusive roles, for example). There are other ways to insert boilerplate.

7

Regarding whether $keywords would work, I’m not sure, but it might. Anyway seems like what I was thinking to do isn’t the ticket. Thanks!

8

It’s a thing, but coercing the generic metadata output into a modified form would be more an academic exercise than anything of practical use I think. It’s the difference between extracting some raw data from a website and then running regex to clean it up—or using the website’s API to produce the text you want from the start. The former is more a technique of last resort—say if there is no API.

To be clear I’m speaking of more than just using keywords and one token. The screenshot demonstrated a number of different metadata fields, and naturally the manner in which they were typed in is freeform. I’m talking about the whole YAML header block here, not just one placeholder.

9

Ah, yes. The use of Synopsis could be helpful for my blurbs, maybe. Might be worth a try. One of those yak-shaving things, though, compared to just doing what I currently do … :slight_smile:

10

Ah. What I was missing below is that keywords are per document not per project.

I was thinking one Scrivener project with several website articles in it. One project per article would be OK but keeping them together seemed more organized. I was thinking top level Scrivener folder = website article = website folder, containing that Scrivener folder’s compiled contents as index.md, for feed to Jekyll. I was imagining a splitter file to move from the single compiled Scrivener file to the various folders.

However, each article needs its own YAML with title, date, blurb, and keywords, and none of those are the same from article to article.

As I understand it right now, I could grab. the title from the top level folder name, the date from the creation date of that folder. I can grab the blurb from the top document synopsis and the keywords from the top document as well.

I had been thinking just typing the YAML might be easier but now that I finally have it through my thick head, maybe I can make this work, given a more powerful splitter and a scheme for naming folders.

I’ll try to publish what I do somewhere in case anyone else wants to do something similar. Examples really help with Scrivener because you only have to select a few thousand of the 15 million options … :slight_smile:

11

Here is a simple example of what I have been describing. The project has two articles, structured as a folder to represent each article with subdocuments containing the text. The metadata for each article is given to the folder itself, which is responsible for printing the metadata block. I’ve placed keywords and the custom field in the outliner for ease of use and reference. You can also see the blur, as a synopsis, for each folder.

Now in the compile settings, if you click on the “Section” layout at the top of the preview column, you’ll see the two article headings highlighted. These are the items the custom crafted metadata block will be pulling from. In this sense, it is similar to when you went into Section Layouts and ticked the “Metadata” checkbox—those items using this layout will print metadata.

Of course the difference is that instead of using the stock “Metadata” block, we’ve designed our own to look the way we want, to use preferred field names and only those fields we want. To see where this is done, double-click on the “Metadata Example” compile format, and check out the “Heading” layout. In the “Prefix” tab is this block of metadata. Again all of this will be pulled from the binder item that uses this layout directly.

So from your perspective, in terms of usage of the project, you aren’t directly concerning yourself with metadata blocks in the binder—that is a function of how the binder will be exported. You simply use the GUI normally to add metadata as you use it.

The one other notable thing is that in the project’s compile settings itself I removed all metadata fields. Presumably the output will be a series of articles, meant to be split up by the script. Each article has its own metadata—we don’t want a block at the very top of the file.
custom_metadata_block.zip (96.1 KB)

12

Super, I’ll compare that to my scheme. Sounds verbally like it’s similar but the details will help.

Much appreciated, thanks!

13

I’m not sure who you’re asking, or what you’re asking for, but to answer your question specifically from my side: no I haven’t developed this illustration any further. :slight_smile: It is meant more to be an example that someone could take and adapt to their own purposes.

14

I’m asking here, because I think my question is related to this one.

I would like to compile a whole multi-document Scrivener project in to a single markdown file, and have a block of YAML metadata at the beginning of the generated markdown file.

Which would be the best strategy to add it? A separate document right at the start of the project, to be checked when compiling in this format?

EDIT: Forget it. Either my proposed solution, or the Metadata section of the Compile format.

Paolo