Setting up the project

If this is going to be about creating GitHub Pages in Scrivener, we’re going to need a GitHub project. Let’s set that up. We’ll call it scriv-git-pages, and make it public in case anyone ever reads this.

That’s done, and I’ve cloned the project to a folder in my Dropbox. Now we need to set up Pages. I think you do that in GitHub settings:

We need to decide whether to put this whole project in GitHub Pages or just the docs folder. I guess we’ll do the whole thing, since the whole project probably should be public. It’s set up and working. The site address is https://ronjeffries.github.io/scriv-git-pages/. It looks like this:

A little research tells me that GitHub Pages will put the README.md as the home page of the site, unless you have an index.md file, in which case it’ll be used.

Let’s go for it! Let’s publish what we have right now, and put it in a page with a known name, which we’ll retain for historical purposes. (I wonder if anyone will ever read this. A conversation yesterday tried to assure me that my mission is to emit my own behavior and not worry about whether other people find it useful. Years of Irish Catholic upbringing, however, make that hard to do.

Thinking out loud here, I believe we’ll do two things. First, we’ll compile this, as is, to a convenient name like v20180615.md, namely today’s date. Then we’ll update the README, for now. Then, we’ll create an index file, etc., as time goes on.

It actually went up, and if you want to look at it, it’s at https://ronjeffries.github.io/scriv-git-pages/v20180615.md/v20180615.html. Of course, you won’t know to look until we get things at least a bit better arranged. I’ll leave that file there, but a story goes with it.

That url, with /v20180615.md/v20180615.html, is what I had to use because of how Scrivener does a compile of an MMD, it needs to export all your pictures, and all your text, into the same folder. And the compile window has only one name field in it, so they create a folder with the name you give, and a markdown .md file of the same name, and then when GitHub compiles the site, you get that name with .html instead of .md. Thus the odd name.

Now what I’d like would be to have a folder name like v20180615, and the file name index.md, so that the URL could be something like ronjeffries.github.io/v20180615/ and the implicit lookup for index.html would do the rest. So I looked in the manual and asked on the excellent Scrivener forum. Soon I got the answer, which was so odd and incredible that it took me four tries to understand and believe it. Hold on.

If the folder you compile into happens to have a name ending in _mmd or -mmd, then the name you put in the compile window, like index.md will be applied to the output file only. No subdirectory will be created, and all the files will just dump into your _mmd folder. This bizarre fact is actually documented, on page 530 of the Scrivener manual.

But wait, there’s more.

Normally when MMD is compiled, I guess, they clear the folder and then fill it. Apparently that checkbox in the dialog above ensures that any other files in the folder are left alone: only the ones Scrivener creates are overwritten. The description of this seems to say that the _mmd trick also avoids the overwriting, and that setting the checkbox may write to the parent folder. It’s very confusing. I expect to destroy the GitHub pages at least once because of this.

However, what this suggests to me is that I can get a shorter URL for these early draft copies using the _mmd trick. I’ll try that right now, hoping to create this version right here. And before I do that, I’ll put a version marker at the very top of the book. Then I’ll compile it and push a copy.

That works and it’s preserved at https://ronjeffries.github.io/scriv-git-pages/v20180616_mmd/

Testing the Compile

Top

ToC and Pages