New user help with Jekyll website decision

today I experimented a little with linking in Scrivener. Created a small scrivener project with a few chapters (top level folders inside Drafts) and then each one having some documents underneath. By default this will generate a single large markdown file from compile.

I created some links in scrivener by dragging documents from inside chapter one, onto a document in chapter two. this resulted in creating a link in the document and while using scrivener, the link works as expected.

When I generate markdown there is no link markdown syntax added at all during compile. All link information is ignored in the markdown version.

Is this something I need to use Scrivener a different way to create links that will translate to markdown links?

Ultimately I will need to change these to external links also since the destination will end up a separate markdown file for each chapter…but that will be a separate secondary challenge, first I have to see how we can have scrivener compile markdown links.

In the Compile Settings pane – under the gear icon in the righthand pane – check the box to convert links to Markdown.

1 Like

It definitely compiles some kind of link oriented markdown, but so far I can’t find a single markdown editor that can actually make any sense out of what it is currently generating. Has anyone else ever actually used this feature?

it seems to change the headers of linked-to things to include a generated reference string…which destroys the look of the document and also tries to link to that, but doesn’t work. I don’t think doing what it should be doing.

For example, I linked one section (the entire section) by dragging that scrivener document onto the page of another. The link works in scrivener. After compile, I went up with markdown link like this

[part 1][]


[part 1[ref1]

The word ref1 was not written by me, totally generated by the compiler, but where to find it? later on it added a header section that looks like this

## part 1 [ref1] ##

I guess that header was added as part of the section processing to add chapter titles automatically, I could theoretically remove that, but then the link wouldn’t work and actually it doesn’t work anyway…so really this is just not correct markdown being generated as far as I can see.

But anyway, in my case, I will have to run this through a post script…so maybe I can fix the output so that it works after going through Jekyll, I can try to write a script that goes through looking for auto generated names like e"ref1" to try to make sense out of it, but this is already getting into nonsensicalness to me… I might be barking up the wrong tree here…

Here is a fresh test project (blank template, minimal changes, Multimarkdown compile option, though I tweaked it to run Pandoc/MMD to generate HTML to see the results): (99.9 KB)

The markdown looks like:

Cupcake ipsum dolor. *See also* section "[The Moon][]". Sit amet marshmallow topping cheesecake muffin (detailed in the [Discussion][]). Halvah croissant candy canes bonbon candy ([but note otherwise][The Sun]). Apple pie jelly beans topping carrot cake danish tart cake cheesecake. 
# The Moon
# The Sun
# Discussion

Note there are no IDs added to the headings. Both MMD and Pandoc auto-generate links. Here is how Pandoc transforms the markdown generated by Scrivener:

<p>Cupcake ipsum dolor. <em>See also</em> section “<a href="#the-moon">The Moon</a>”. Sit amet marshmallow topping
cheesecake muffin (detailed in the <a href="#discussion">Discussion</a>). Halvah croissant candy canes bonbon
candy (<a href="#the-sun">but note otherwise</a>). Apple pie jelly beans topping carrot cake danish tart cake cheesecake.</p>

<h1 id="the-moon">The Moon</h1>
<h1 id="the-sun">The Sun</h1>
<h1 id="discussion">Discussion</h1>

All links work fine.

MMD or Pandoc will add the correct #ID references by default (the rules for generating auto-ids are fairly straightforwards: Pandoc - Pandoc User’s Guide). I’m not sure how you got ref1, you can share your project to see where you went wrong.

1 Like

please tell me how to do it then, my results don’t match yours

The project I attached is a full test case, you can look at it, compile it etc. It also demonstrates some simple style transforms (emphasis, small caps etc.). All I did was select text and drag binder documents over the selected text, and enable links>MMD in the compile options.

Now the question is whether kramdown does what MMD or Pandoc can do, generate auto-ids? If not, you may need to work out how to get this to work. You could add manual #ids (# Header {#id} in both pandoc and kramdown) but getting auto-ids working would be simpler…

I will take a look at that tomorrow, thank you!

I have a separate question for you that I am trying to figure out at the moment. doing compile I want to insert some markup pre and post section…that is pretty straight forward but do you know if its possible for that markup to include metadata values from the scrivener document? If I have a custom meta data saved in the document, when its compiled, can I use that metadata to fill in some of the markup that I want to add?

Yes, custom metadata can be inserted using the Section Types:

This is an example from my Quarto template, where a multi-part figure section has #id .class and attributes set up as custom metadata for each document. The compiler uses <$custom:metadata> to reference this and insert the correct value. Scrivener has a bunch of these <$placeholders> which are flexible ways to get values into a compile…


Thank for that, love your Scrivener theme by the way.

So that worked as you explained, one quick question about using placeholders and custom metadata this way, is there a way for the compiler to detect if the metadata is empty and not put extra space in there when it is?

for example, I’m using a custom meta data called “syntax” and its actually only relevant for one type of document which I will definitely assign a unique section type to, but anyway that custom meta data is a list and sometimes it will be left empty. I already changed the default from "None’ to nothing…but during compile an extra space or two is inserted in place of <$custom:syntax> instead of actually nothing.

Any way around that you can think of? Also do you know if its possible in some way to have custom metadata that will only be applicable to one particular section type?

I’m gonna circle around to the links example you sent me, later today. One question I will ask once I look at it, is the procedure you used while making your scrivener project to create the actual links.

I think first of all the reason the one I did didn’t work is because I used section only not section+header in the profile. In your example the compiler generated a header for each sub-document. That is the think that markdown needs to in order to end up as linkable.

Secondly I don’t know why MMD inserted the ref1 and ref2 values…no idea how or why they did that…,.

I’ll try to do another test that doesn’t have so much junk data in it and see if I can replicate again to figure out what I’m doing wrong. Guess the sample did wasn’t proper without a header anyway, so rule number one for links is to only try to link to a md header…whether I put one in the middle of a sub-document or the sub-document section will be using section+generatedheader in compile…either way it will need to be there for the typical single-[document scrivener result.

I will breaking things up sooner or later into more files for the website, in which case they have to be transformed into external links in some or most cases where the link is referring an entirely different blog post that has been isolated to a different file. I’m not sure how right now, to put that into generated MD so that these external links in the MD will go through jekyll and end up pointing to the right thing. Have to think that one through a minute.

Select a word in the editor, drag a document from the binder onto the word. You could select the word and use the “Link to document” context menu too…

No, metadata is a project-wide setting and so it is up to the section type to specify which metadata it will use.

Well for text, an empty metadata field is replaced with “”, i.e. nothing. For a list, if I replace “None” with “” I don’t see any spaces introduced. I think you mean in the section type that if you do { <$custom:type> } and custom:type is empty you get: { } — in which case no way that I know of, there is no conditional rule for this and it would probably require some regex replacements (you could try the Compilers replacements, or an external script)…

No I was getting an extra space. I’m not sure why right now.

actually I think I figured out why. Here is what I have for Prefix in compiler:

{% highlight <$custom:syntax> %>

The extra space is not in the meta data is in the above. In the case where its empty there is extra space.

I probably need to change the actual metadata list so that each entry in the list has a leading space and then do the markup here like this:

{% highlight<$custom:syntax> %}

Or else just live with the extra space because it doesn’t really matter in this case, but at least I know what I was doing wrong.

I would advise against using Scrivener until they fix the ‘compile’ feature. It’s just impossible to understand at the moment.

Not for me. Not complicated. Complex with features, yes. That’s a benefit.