Advice re GitHub pages markdown book

I’m writing a little “book” in Scrivener, to be published on GitHub pages. Documents there are basically HTML pages, generated by GitHub (using Jekyll) from markdown files that you submit, .md files.

I’m following AmberV’s approach to compiling for LaTeX, with a Ruby post-processor that I’m writing / adapting from Amber’s.

I’m compiling to plain text, because Scrivener basically prevents you from putting markdown in your document if you’re compiling to markdown. (!) I imagine that to compile to markdown you need to define and use a bunch of styles, which you can then format to put the pound signs and such in front. Maybe some other time, right now I’ll just type ## Heading when I need it.

I do need some other things for which I’m requesting advice.

First, it would be nice to create a previous / top / next link at top and/or bottom of each page. I would like to do this with prefix-suffix for my section type, if possible. This would look roughly like this:

prev | top | next

I see no way in Scrivener to access the previous or next title (especially at the same level, which I’d need). I’m considering just naming my chanpters 1.html, 2.html and so on. Amber uses <$n:fileID> to put a serial number into her file name separators, plus title. If I just used the number, then the above, for chapter 5, might be:

prev | [top]1.html) | next

I might be able to initialize some $n:prev and $n:next so as to make that work. Ideally, there’d be some way to save the previous and next titles as well, to customize those links, but that’s probably more yak than I need to shave just now.

Anyway, please offer ideas and hints for how one might do this sort of thing. Links to stuff to read are welcome.

For extra credit, I’d welcome ideas on a table of contents as well. My best guess for that is a separate Compile, with layouts that just include something like the title, with a running number, perhaps again with $n:chapter or something.


OK, I tried this as my prefix:

[code]>>>> <$n:fileID>-<$title_no_spaces>.md

prev | top | [next][<$n:next>][/code]

And it nearly works. By putting a <$n:next> in the first file, I was able to get $n:next to increment correctly. But $n:prev starts out as 1 and needs to be one less than the current file number. My best idea so far is a custom layout for the index (first page), that doesn’t reference $n:prev.

(Update: That actually works. Made a custom first page with <$n:next><$n:next> that will be in hidden text, and a custom layout for that page that doesn’t use the prev and next items. I think I can extend this to put the links at both top and bottom “fairly easily”.)

Better ideas welcome!

And a problem. layout suffix is added at the end of the upper level, not after inclusion of sub levels. (One obvious way to do it, I admit.)

What I need for a link at page bottom, however, is for a suffix that gets added after the last page of a sub level.

One horrible way to do that would be to manually tag the last sub-page, but that’s error prone as well as tedious. Given

some sub text

some more sub text[/code]

Is there a way to add something ala a layout suffix, after the last sub text?

Hm … or maybe I need to do the footer before emitting the >>>> for the page breaks?

Sorry for thinking in public here but maybe when done this thread will be useful to others.

So, now my prefix for pages looks like this:

[prev](<$n#prev>) | [top](1) | [next](<$n#next>)

>>>> <$n:fileID>-<$title_no_spaces>.md

[prev](<$n:prev>) | [top](1) | [next](<$n:next>)

Which nearly works, except that $n#prev isn’t defined first time around, and therefore comes out as a literal n#prev in the first (fake) page suffix.

If I increment it secretly in the first page, then it’s good in the first page, and one too large in all the others. I can hack that, I imagine, by referring to it only with # in actual use, then secretly incrementing it in an html comment.

Or, maybe I should put the whole page-break logic as a suffix rather than a prefix, and do the whole first page manually?

(Most of this was written before any of your follow-ups.)

It sounds like you have the rich text conversion feature enabled in your compile settings (under the General options tab on the right side of the overview screen). As noted in the manual, that setting is for people that don’t use Markdown, but want to take advantage of its processing engines. :slight_smile: So yeah, it’s not going to work right otherwise.

A better setting, if any, might be the one right below it that only converts tables and lists. It doesn’t hurt anything to have it on unless you really want tables and lists to look weird for some reason. I type in plenty of my own Markdown into the editor, and I use that setting. If anything Scrivener’s default settings are designed for people that do want to write in Markdown, rather than avoiding it, it has always been that way. All of the styles stuff you refer to are options you have to go out of your way to set up in most cases (we do configure a few logical defaults, such as putting “>” in front of paragraphs marked “Block Quote”).

That’s something Scrivener itself does not do. It has placeholders for accessing the ancestry of the current item, such as <$parenttitle> or <$level2_title>, but not siblings. There would be ways you could do this manually with custom metadata, but if you’re going that route you might as well just type in the links yourself into the editor!

Aside from the techniques you are exploring, the way I would approach this is to handle it in the post-processing phase, in much the same way that metadata and footnote/image reference data is inserted into each temp file. That’s a bias in how I think to be sure; I don’t expect software to do everything I can imagine, I expect software to do just good enough for me to pick up the job in an interface where that is not a problem, like a programming language. It’s not the One Right Way, but it’s how my brain works.

In the example script you’re working from, I used an unordered dictionary to store filenames and links to the associated temp file, so it would require a little modification to turn it into a linear script so that you could look back and forwards one array index to get the next/prev file name. Beyond that, it would just be a matter of doing that and then inserting the Markdown links based on that information at the top of every file.

And that incidentally would help solve the ToC problem too. If the filename array is build in a linear fashion to start with, then you can insert a loop that goes through that and builds a ToC, then insert that at the top of the first file.

You could certainly try and tackle some of this in Scrivener itself, but it’s not really built to handle looping and logic on the user side. For example one way of making a ToC out of a project would be to create a compile format that formats the draft as a ToC—similar to how the outline style compile formats work—but then you’d have to switch to that, compile a file, switch to the main matter format, compile that, open both files and glue them together in an editor, etc.

Yeah, the Separators pane might help you out here, instead of using the Section Layout prefix and suffix. The latter work better when you always need a prefix or suffix, the former work better when you want to stick stuff between sections. Their logic works in groups of like files. The “between” type separator inserts stuff between similarly typed binder items, the “before” and “after” separators then would enclose that entire segment of like items. If that doesn’t make any sense, check the user manual on this pane, it has a few figures and illustrations explaining how it all fits together.

Thanks, Amber.

Yes, I’m with you on doing more in post, and certainly know how to do that, being a programmer and all.

I’m really trying to get the Scrivener yak under control, so doing as much as possible in the system has value for me.

I’ll look at separators. At this writing I have no idea what they do, but from the name I think I have a pretty good guess, and if my guess is decent, yes they might be better.

BTW, I’d buy a pizza for whoever gave me the ability to init a <$n::prev> to zero instead of one :slight_smile:

I think I’m happy writing in pure markdown, and compiling to plain text, and don’t think I’ll try to get it to do the markdown for me, certainly not in this document. On one of my first tries with Scrivener I went for styles and formats, headers and such, and we didn’t get along on that. Perhaps as I learn more about this way I can find some useful ways to let it do a bit more of the lifting, but I’m used to full markdown anyway, so that’s good.

Agreed on the dictionary and ToC. Presently I think I’ll name the actual files 1,2,3, but put some title info one the >>>> line as well, to tuck away for things like ToC. I’ll know more when I’ve shaved a bit more hair off this thing. The good news is I’m closer to the skin than ever before with Scrivener.

Thanks again (and again) for your rapid and comprehensive help! I’ll keep shaving!