Tuesday, March 21, 2017 No comments

Tech Tuesday: Roll Your Own Writing System, part 6: Jekyll

The series rolls to an end…

In Part 1, we had a look at Markdown and the five or six formatting symbols that cover 97% of written fiction. Part 2 showed how you can use Markdown without leaving the comfort of Scrivener. Part 3 began exploring eBook publishing using files generated from both Scrivener and directly from MultiMarkdown. Part 4 provided a brief overview to a different tool called Pandoc that can convert your output to a wider variety of formats, and is one way to create print documents for beta readers or even production. Part 5 described how to use MultiMarkdown’s transclusion feature to include boilerplate information in an output-agnostic way, and how to use metadata variables to automatically set up front matter.

Scrivener is an excellent writing tool, and we have seen how using it with MultiMarkdown only makes it better. But there are conditions where abandoning the GUI for a completely text-based writing system just makes sense. For example, you might want to go to a minimalist, distraction-free environment. You may want to move to a completely open-source environment. Or you might need to collaborate with someone else on a project, and Scrivener really isn’t made for that.

Don’t Hyde from Jekyll

Jekyll is the most popular static site generator. You write in Markdown—Jekyll’s particular flavor, which is similar to MultiMarkdown in many ways—and if Jekyll is running, it automatically converts your pages to HTML as soon as you save. It even includes a built-in web server so you can see what the changes look like.

If you’re on a Mac, installation is almost too easy. Drop to a command line, enter gem install jekyll bundler, and watch a lot of weird stuff scroll by. It’s as easy on Linux, if you have Ruby 2.0 or newer installed. On the Microsoft thing, there are some specific instructions to follow (I installed it on my work PC, no problem).

Once it’s installed, get going by following the quick-start instructions.


Unlike Scrivener, organizing your project is on you. But there are a couple things that might help:

Each story or project should live in its own folder. Within that folder, tag each chapter or scene with a number to put everything in its proper sequence. For example:


It’s a good idea to increment by 10 as you create new scenes, in case you need to insert a scene between two existing ones later. To move a scene, change its number. If you have more than nine chapters, use four-digit numbers for the sequence. (If you need five-digit numbers, you should seriously consider turning that epic into a series of novels.)

Differences from MultiMarkdown

Like MultiMarkdown, Jekyll’s flavor of Markdown supports variables and transclusion. But there are a couple differences. In Jekyll, variables look like MultiMarkdown’s transclusion:

{{ page.title }}

You can draw variables from the page’s metadata, or from the _config.yml configuration file (in which case you replace page with site).

Transclusion is a function of the Liquid templating language, built into Jekyll. To include a file:

{% include.relative file.md %}

You can also use include instead of include.relative to pull files from the _includes directory. By using Liquid, you can specify parameters to do different things, effectively creating your own extensions.

For example, here’s how you might do section breaks:

<p class="sectionbrk">
  {% if include.space %}&nbsp;{% else %}&bull; &bull; &bull;{% endif %}

So if you just enter {% include secbrk.html %}, you get three bullets. To get a blank line, enter {% include secbrk.html space="true" %} instead.

Also like MultiMarkdown, Jekyll supports a metadata block at the beginning of a file. While they look very similar, Jekyll uses YAML format for its metadata. The upshot is, a Jekyll file begins and ends its metadata with a line of three or more dashes, like this:

title: The Sordid Tale of Woe
author: Henrietta Jekyll
permalink: /sordid/sordid_tale.html

Certain metadata tags are special to Jekyll. For example, permalink specifies the name and location of the HTML file Jekyll creates from the Markdown source. Another important tag, layout, can be used to choose a template. You can set the default layout in the configuration file, then use a second configuration file to override it for doing things like publishing.

Git Out

Jekyll is also a blogging tool. Your posts go into a special directory, _posts, and have a specific naming convention. Two additional metadata tags are important:

date:   2017-03-21 07:00:00 -0500
categories: writing technology

The date entry specifies the date and time your post goes live on the generated site. The categories entry lets you tag each post for easier searches.

But all that’s just pixels on the screen unless you have a place to put your site. That’s where Github Pages comes in. You can upload your Jekyll files to Github Pages, and it automatically updates your site when it finds new or changed content. This is pretty useful, but it’s even more useful when you’re working with other people. Everyone has their own copy of the source files on their own computers, and they can each push (update) their changes as needed.

Now What?

I hope I’ve given you some ideas for new ways of looking at your writing, and how to make the publishing part more efficient and more collaborative.

The rest… is up to you. I’d love to see your own ideas in the comments.

Monday, March 20, 2017 No comments

The Brass Mechanism, episode 3

Part 1 | Part 2

Difference engine
Image source: Wikimedia Commons
Liana set their prize on the table, and they stepped back to take a look. It was a strange-looking device, but even folk with a basic education could see it was some kind of machine. All brass gears, spindles, and fittings it was, with a few flecks of the wood that had once covered it still clinging to the supports. It sported a crank on the right side, the wooden handgrip long gone. A row of numbers dominated the front of the device: 104 072 298. Below was a smaller set of numbers: 98 1812. It had a faint odor of oil and decay.

“So what do those mean?” Chakan asked, pointing at the numbers.

“Maybe the answer is in here.” Liana opened the book, watching to see if the pages would crumble at a touch. “Have a care with this, but it might survive our perusals.” She turned up the title page; it felt brittle but did not fall to pieces. “Using the Prediction Calculator,” she read. “What in the Fourth Hell?”

“This hunk of metal tells the future?” Chakan gave the device an incredulous look. “Ha, the Queen would want to get her hands on this, then.”

“This text is hard to make out. They must not have written the same way we do. ‘Accurate predictions… to ensure, against the stars shall you calibrate.’ What?”

“Sounds like Low Speech. Outside of Phylok you get, so the farmers talk.”

Liana took a moment to parse her husband’s explanation. “Ah. So the ancients all talked the same way? I see. This is saying you calibrate this thing against the stars to get accurate predictions.”

“It uses the stars to make predictions? Outlandish. Shipmasters use the stars to tell where they are on the sea, but I’ve never heard of anyone using them to predict the future.”

“Eh. I never heard Low Speech until you used it just now.”

“If the ancients used the stars to predict the future,” Chakan mused, “the sages would find this thing useful indeed.”

“Ah!” Liana cursed as the page tore. “Bring some paper, love. If these gods-forsaken pages come apart on us, we can preserve what they say for the sages.”

“The sages won’t be pleased with our destroying the originals. But if we’re going to puzzle this thing out, it’s the best we can do.” He paused. “Liana… perhaps we should give this over. Let the sages ruin the book. Knowin’ the future could be a fearful business.”

“Could be some profit in it, love. Besides, we found it. We pulled it out of our field. You got the box open. We’ll do the best we can, and that will have to be good enough. Here, write down the numbers it’s showing. Maybe we can puzzle out their meaning later.”

“Aye. Then we’ll sow tomorrow?”

“If the Creator brings us another day of dry weather, indeed. Don’t you have those numbers written down yet?”

“I’m sketching the whole works.” Chakan slid the paper to his wife.

“How do you do that so well, and so quickly?” she asked. In less time than it takes to drink a cup of tea, Chakan had sketched a fair likeness of the mechanism, with Liana looking on. He had drawn a look of wisdom and revealed knowledge on her face.

“A knack. I don’t get to exercise it often.”

“I like this. We should put it in a frame. Then we’ll wait for dark, and calibrate this… this thing. But let’s copy the instructions while we’re waiting.”

“If we don’t destroy the pages along the way.”

“Hoy, I got an idea.” Liana took another sheet of paper and slid it in between the next two pages in the book. “Maybe this will help.” She gently turned the page. “Ha, it worked! Now here’s what it says…”

The night was clear enough to see the stars, and they followed the instructions to calibrate the device. They twisted knobs and pointers on the top of the mechanism as directed, then held their breath as Chakan turned the crank counter-clockwise. One turn, two turns… then the odd clicking noises inside the mechanism ceased and the crank spun freely as the instructions said it would.

They took their prize back inside and looked it over. “Hoy,” said Chakan, “the numbers along the bottom are different, now. Now it’s 84 4269.

“Eh. I think it’s forty-two something by the old Camac calendar,” Liana mused. “And it’s pretty close to the eighty-fourth day of the year. Maybe that’s today’s date.”

“Then this thing has been in the ground a long time, waitin’ for us to dig it up.” Chakan looked at his sketch. Eighteen-twelve. Gods… that mighta been the year of The Madness.”

“Wouldn’t that be something?”

“Liana… let’s give this over to the sages. We’re messin’ with somethin’ that got buried at the worst time ever. Or just before. What was that first set of numbers? One oh-four?” Chakan consulted his transcripts. “First and third groups use the same numbers. An ill wind blows strong. Makes me wonder what the rest of it means.”

“It won’t bring back The Madness, love. That was a good twenty-four centuries ago. We’ve reset it for modern times, and we’ll make some use of it. Then we’ll give it over. Fair enough?”

to be continued…

Wednesday, March 15, 2017 1 comment

Kneecapped 2017, an update

Tonya, Queen of Kneecaps
image source: about.com
When we last left this, the knee had started improving around the time I went to the doc. The day after, the pain decided a brief vacation was all it needed… then the left knee decided to join the fun.

Reality the Crutch has been missing for some time now, but we have a metal adjustable cane laying around, so I adopted it instead to get around. Things were still pretty painful last Tuesday, when I went to the orthopedist. He looked at the X-rays and decided we needed an MRI. I asked him for some happy pills, and he wrote a prescription for hydrocodone+acetaminophen right away. I’d been popping ibuprofen like candy for a while, and it was keeping things manageable through the day, so I figured I could continue that and save the happy pills for night time (the pharmacist said that was OK).

So for the next few night, it was two happy pills before bedtime, wait an hour for them to kick in, sleep like a log until they wore off around 4am, then one more to get me through the rest of the night. Not the best sleep I ever had, but better than what I’d been getting.

After a few days of improved sleep and lots of inactivity, both knees started getting better. From experience, I know this is the dangerous phase of a knee problem—it’s way too easy, now that you can get around without tons of pain, to overdo it and go right back to where you started. So I rested as much as possible, moved when I had to. Icing started doing what it should, so I went back to doing it, alternating knees as needed.

The MRI was on Monday, and was anti-climatic. Laid on a pallet, knees propped up, moved as little as possible while this big round thing spent 20 or 30 minutes making weird noises. Today was the interpretation. Long story short, he wants to do a full replacement. There’s a lot of crud in there, and roto-rooting it won’t take care of it. Due to long-scheduled travel, this isn't going to happen until May, but in two months I will post Tonya for the last time.

Tuesday, March 14, 2017 No comments

Tech Tuesday: Roll Your Own Writing System, part 5: Reuse

The series rolls on…

In Part 1, we had a look at Markdown and the five or six formatting symbols that cover 97% of written fiction. Part 2, showed how you can use Markdown without leaving the comfort of Scrivener. Part 3 began exploring eBook publishing using files generated from both Scrivener and directly from MultiMarkdown. Part 4 provided a brief overview to a different tool called Pandoc that can convert your output to a wider variety of formats, and is one way to create print documents for beta readers or even production.

Way back in Part 2, we used Scrivener to embed HTML separators between scenes and for internal scene breaks. As we saw last week, that doesn’t work when you need to output to a different format. As it turns out, there’s a way to work around that by using MultiMarkdown’s transclusion mechanism. Transclusion and metadata variables provide the capability for reuse, pulling common boilerplate files from a library.

Inclusion… Transclusion?

Transclusion is a technical term, but it’s easy enough to explain. You use it to embed another Markdown file into your document, like you might include a graphics file. A function like this is essential when you’re maintaining a collection of technical documents, because you can reuse common sections or passages—write them once, store them in a library of common files, and then changing one of the source documents automatically updates all the documents that use it. For fiction writing, it’s a good way to pull in all those boilerplate files (about the author, front matter, etc.) that you need for each book.

To transclude a boilerplate file, put this on its own line:


When you run multimarkdown, it pulls in the contents of myfile.md and processes it.

Now here’s where it gets fun. Say you really need to be able to output to both HTML and OpenOffice. Instead of embedding HTML that gets ignored in the OpenOffice conversion, or vice versa, you can use a wildcard:


Now, when you output to HTML, multimarkdown transcludes the file myfile.html. When you want OpenOffice, it uses myfile.fodt. You just have to supply the files with the right extensions and content, and you’re off to the races! You can use this in the Separators in Scrivener to choose the right markup for your output.

A few caveats for fodt transclusion: You cannot use entities like &bull; or &#8026; to specify special characters. You have to enter them as characters. If you only have one line to add, you don’t need to put any OpenOffice markup in the fodt file—plain text is fine, but use the right extension so multimarkdown knows which file to use.

If you want to reuse transcluded files with other documents, you can add another line to the metadata:

Transclude Base: /path/to/your/files

You can use a relative path like ../boilerplate, but it’s safer to specify the entire path in case you move the file to some other location.

Does the Front Matter?

But transcluding boilerplate files is only the beginning. Especially for front matter, you need to change at least the title for each book. Fortunately, MultiMarkdown has that covered.

In Scrivener’s Compile window, the last entry is Meta-Data. Back in Part 3, you used this to specify a CSS file for HTML output. Scrivener pre-fills entries for the Title and Author, but you can add anything else you want here. All the metadata ends up at the beginning of the file, where MultiMarkdown can process it further.

So you might have a block that looks like this:

Title: Beyond All Recognition
Subtitle: The Foobar Chronicles, Book 1
Author: Marcus Downs
Copyright: 2017
Publisher: High Press UR

Create a title page that looks like this (for HTML output):

<div style="text-align:center" markdown="1">



Copyright [%copyright] [%author]. All rights reserved.

Published by [%publisher]



Instant front matter! The {{TOC}} construct inserts a table of contents, another Multimarkdown feature.

Now What?

Now you know how to include boilerplate files in your book, and how to automatically put the right text in each output format.

Next week… it’s something completely different to wrap up the series.

Monday, March 13, 2017 No comments

The Brass Mechanism, episode 2

Part 1

Image source: Wikimedia Commons
“It’s as tight as I can make it,” said Chakan, clambering out of the hole.

“Maybe it’ll work this time, then.” Liana tugged the ox’s harness. “Pull, ya great thudding beast!”

Chakan admired his wife as she coaxed the ox to keep pulling. She even knows the right language, he thought. The animal strained against its harness, and… “Hoy, it’s coming up!”

“Keep it coming!” Liana told the ox.

“Stay on that side,” Chakan warned. “If the rope snaps…”

“Yar. Easy… easy… ha!” The block surrendered its grip on the surrounding earth and slid up the slope and into the field. “That’s it! Drag it back to the barn!”

At the barn, they returned the ox to its stall with a bag of feed, then looked over their prize. “Eh,” Liana mused, “it might make four or five pavers. Enough for our needs, anyway.”

“Aye. But… look.” Chakan knelt and ran his finger across one side. “Looks like a line here.” He brushed away dirt. “I think it runs all the way around the thing. Like it’s a lid.”

“Ha! Maybe it is a chest full of octagons, then?”

“Could be.” Chakan tugged at the “lid,” but it did not budge. “Probably sealed. Here’s where the plow hit it.” He rubbed at a scuff mark along one side. “Hate to take a hammer to it, we might could use it for something.”

“Here, let me bring the pry tool.” Liana kissed her husband. “Keep looking it over, love. You might find something.”

“Best bring a knife, too,” Chakan called after her. “I doubt I could slip that pry tool into this tiny crack.”

“Hoy, I got an idea. Wait here.”

A few minutes later, Liana had driven an old knife blade all the way around the thin crack, and pounded others into each corner. “Yar,” she said, sitting on the ground opposite from Chakan. “Now, twist your blades on your side, and I’ll twist mine. If we get it right, we might get this thing to slide up. Ready? Now.”

“Hoy, the blades are loose,” said Chakan, after a minute of twisting and pulling. “Aye, we got it up a little.”

“Yar. I think we can get the pry tools in there now.”

The afternoon rolled by, and still they strived to open their prize. At last, they worked the lid a finger’s width up, and yet it would not lift off.

“Is it my imagination,” Liana mused, “or is the lid pulling itself back down? Have you ever seen such a thing?”

“Enough,” Chakan growled, standing over the block and working his fingers into the gap on either side. “This ends now.”

“Don’t hurt your back,” Liana warned.

“Eh, I’m more worried about my hands here.” Chakan gripped the block with his boots, pushing with his legs and pulling with his hands. “Get loose, ya Goblin-spawn!” He strained, his accent and curses growing thicker. “Ah, that’s it… come off!” At last, the lid gave way with a pop and a tearing noise, neither of which had they expected to hear from a stone box. Chakan dropped the lid in the soft dirt and panted for breath.

“What in the Seventeen Hells is this?” Liana wondered, looking into the box.

“Eh. Shoulda just handed it over and let the sages do the hard work,” Chakan grumbled, thinking about the Rules of Finding, part of the agreement they signed in exchange for the land grant: Stonework, you may do with what you will. Money is yours but for the normal tax. Items of interest should be turned over to the sages, that they may be studied and benefit the entire nation. “That’s an item of interest if I ever saw one.”

“Yar. We’ll turn it over. But the Rules don’t say we have to turn it over right away. Let’s take a look at it ourselves, first. We did the hard work of getting the box out of the ground and getting it open, so we’ve earned that much.” Liana looked at the box. “Clever folk. Whoever boxed this thing up meant it to survive the ages.” She pointed at a layer of black gunk around the top edge, then turned the lid over. “They painted pitch on the inside of the box and lid, see? It sealed the box tight. That’s why it was so hard to open. I wonder how old this thing is.”

“Well, everything in the ground out here has to be from Camac That Was, nay?”

“Yar.” Liana reached into the box and lifted the contents out. Some kind of mechanism, it seemed; the tarnished brass struggled to reflect the light. “Welcome back to the sun. Now what are you?” She looked down. “Chakan, there’s a book in there. Maybe it’ll tell us what this thing is.”

“If we can make heads or tails of it.” Chakan picked up the book, wincing at the twinge in his back. “I just hope this was worth the effort.”


Tuesday, March 07, 2017 No comments

Tech Tuesday: Roll Your Own Writing System, part 4: MultiMarkdown and Pandoc

The series rolls on…

In Part 1, we had a look at Markdown and the five or six formatting symbols that cover 97% of written fiction. Part 2, showed how you can use Markdown without leaving the comfort of Scrivener. Part 3 began exploring eBook publishing using files generated from both Scrivener and directly from MultiMarkdown.

Today, we’re going to take a brief look at a different tool you can use to publish MultiMarkdown files.

Pandoc describes itself as a Swiss Army knife for markup languages, but it goes farther than that. More than markup languages, it converts to and from common word processor formats and can even convert directly to EPUB. You can mess with templates to get the output really close to production-ready, but that's a little beyond the scope of our series here. In real terms, it’s not any faster than loading a prepared HTML file into a skeleton EPUB; both methods need a little cleanup afterwards.

This sounds at first like it’s just an alternative to using MultiMarkdown, but it goes a little farther than that. One problem with embedding HTML in your Markdown files, none of it gets converted to other formats. So you can’t just take your MultiMarkdown file and create an OpenOffice file by running:

multimarkdown --to=odf story.md >story.fodt

Because all your section breaks disappear. Pandoc ignores embedded HTML as well… so again, what does Pandoc buy you?

Well, once you have your HTML file, you can use Pandoc to convert that HTML file to the word processor format of your choice.

pandoc -f html -t odt -o story.odt story.html

And there’s the answer to how you make your story available for beta readers who want a word processor file. If you’re willing to tolerate some sloppy typesetting, you could use it for your print document as well. Pandoc also supports docx and rtf as output formats.

Now What?

Now you can output your MultiMarkdown file in a number of formats, including eBook (direct and indirect) and common word processor formats.

Next week, we’ll look at some special features of MultiMarkdown that you might find useful.

Comments? Questions? Floor’s open!

Monday, March 06, 2017 No comments

The Brass Mechanism, episode 1

Difference engine
Image source: Wikimedia Commons
The thought crossed Chakan’s mind: Plowing’s a man’s work.

The better part of himself spoke up immediately. You know better, ya lout. Reacher women plow when they have to. Two years you’ve been a Matriarchy man now, you shouldn’t think like that anymore.

He looked across the field, where his wife Liana plowed with the other ox. And she’s plenty able to do it, a third part of him thought, with mixed admiration and desire. Chakan had always found sturdy women more attractive than either the willowy Reacher standard, or the round soft kind favored in Westmarch and the Alliance cities. They would be married a year, come the autumn equinox, and Chakan often thought how lucky he was, to—

The plow lurched, nearly jerking out of Chakan’s hands. His surprised “Hoy!” did not cover the scraping of the plow blade dragging across a rock. “Hold up, ya lump!” he yelled at the ox.

“What happened?” Liana called from her side of the field. They had each taken half to plow, and now they were close together. Closer than Chakan had thought; they were nearly finished.

“We found another paver, like as not.”

“That’s good. We need a few more to finish the walkway.”

“Maybe that’s why the Crown granted us this patch,” said Chakan. “We’ll never find the end of clearing it.”

“Every time I think about it, I marvel at how vast Old Stolevan must have been. You can hear legends of Camac and Stolevan carrying a million folk each until your ears fall off, but to think this was part of the city…” Liana trailed off, looking toward Queensport, visible to the southeast. “Its boundaries stretched clear out to here and beyond. Well, mark the spot and we’ll dig it up after lunch.” She gave him a wicked grin. “But not right after lunch, mind you.”

“How much longer?” Chakan asked, somewhat later, lying in bed with his wife. This was their favorite dessert after any meal.

“Oh, the Healer said not to worry about it right away. I’m not even showing yet.” Liana had kindled two months ago, to their mutual delight. “If all goes well, we might not have to stop.”

“That’s good to know.” He rolled onto his side, draping an arm across his wife.

“Will you love a daughter as much as a son?” she asked.

“Of course. She won’t be the only one we have.”

Liana stroked his hip, then slid her fingers down. “Good. Hoy… I think you’re ready for more.”

It was mid-afternoon before they pushed themselves grumbling out of bed. But Liana was right; they needed a few more pavers. They had dug up many cut stones last fall and laid them between their house and the barn—a tiny barn by the standards Chakan had grown up with, big enough to house their oxen and what little hay they needed for a southern winter. They were plowing two months before farmers would in the Northern Reach, and needed far less hay to keep their livestock fed through the winter. Still, what they called “winter” along the southern coast was wet, and the paving stones helped them stay out of the mud.

They took shovels, a pick, and rope from the barn, then trudged across the field toward the stick that Chakan had used to mark the spot.

“Maybe this one will be a chest full of octagons,” Liana quipped, getting to work.

“Aye. And maybe we’ll get a winter without snow,” Chakan laughed, digging next to her.


“Oh, aye. A Reacher saying. The land up there is still covered with it, and here we are getting ready to plant.”

“No, love.” Liana tossed another shovel of dirt aside. “What is snow?”

“You don’t—of course you don’t know about snow, if ya grew up in Queensport. Well…” Chakan stopped to think. “It’s like rain, but it’s frozen before it falls from the sky. Instead of drops, it comes down in tiny little flakes. Enough to bury the land, sometimes as high as me.”

“Ah, I’ve seen that a time or two. Enough to cover the ground, sometimes, but…” Liana grounded the shovel. “Tell me true, Chakan. Is that a tall tale you tell about it covering the land?”

“Tell ya true, Liana. The ground around the warm springs stays clear, but everywhere else? Snow as far as ya can see.”

“No wonder you moved south,” she grinned.

“Nay, nay. I moved here…” he stopped, realizing she was teasing him. But the warmer climate was the least of his reasons to leave his old home for this strange nation where women ruled. As a younger son, he had little to inherit. In his youth, he learned he was not cut out for the military. The one girl he fancied took up with a boy with better prospects. He hired himself out as a roustabout, a freelance farm hand, and found he liked the work. But that desire for one’s own land, one’s own place, was in the Northerner blood. The Matriarchy’s embassy promised land to those who would emigrate and embrace their customs…

“Hoy, ya lazy lout, stop woolgathering!” Liana laughed. “I think I just hit it.”

“Eh? Sorry.” Chakan put his back into it, and soon they looked at the corner of a stone.

“That might be enough to finish the walkway,” Liana mused. “Depends on how deep it goes.”

“Only one way to find out,” Chakan grinned, and began digging around it.

A few minutes later, they stopped. “Eh,” Liana grumbled. “Looks like a block. ‘Twould make a fine cornerstone for a tavern, but it ain’t much good for us.”

“We could always hire a stonecutter to split it,” Chakan pointed out. “That’s enough stone to finish the walkway, and give us a good start on a walk to the road.”

“If she don’t shatter the thing. No telling how long that block has been buried. Well, fetch an ox, husband. We’ll get this out of the field, then we’ll decide what to do with it.”

to be continued…


Related Posts Plugin for WordPress, Blogger...