- Draft your novel or short story or poetry in your favorite text editor
- Structure it in markdown
- Style the markdown with these Manuscript CSS stylesheets
- Impress your friends and family (or critique group) with a work that mimics industry standard manuscript formatting
Are you a writer? In particular, a writer of narrative works? Fiction, narrative nonfiction, memoir, etc? Do you draft using a markdown text editor? And do you wish to share your drafts in a professional manner without having to port your work to a word processor? Save the fancy office word processors like LibreOffice or Google Docs or Word for finalization when you are ready to submit your work somewhere. Now, you can stay in your favorite markdown editor and still have a means to present your working drafts in a professional manner for review, critique, or whatever.
Take a look at the PDFs in the templates folder in this repository. These manuscript-like documents were rendered from their corresponding markdown-formatted draft documents. No fluff and easy to read and review. Here are some screenshots of the results . . .
- Manuscript formatting similar to what many call Shunn Formatting: https://www.shunn.net/format/ (the "modern" formats)
- Prose manuscripts: short (scenes), long (chapters, scenes), narrative, nonnarrative
- Poetry manuscripts: single or multiple poems, many poems (chapters, poems)
- US Letter, A4, and … though you shouldn't, A5, A6, US Half-letter
- If you are CSS savvy, easy-to-alter settings for nearly everything (fonts, margins, spacing, even the dinkuses and the -30- indicator).
- This process is not for book production
A manuscript is not a formatted book. It's an industry standard format used to share your work with other humans for review and comment.
If you are looking for something to format your work for self-publication, import your work into something like Vellum, Scribus, InDesign, Atticus, Reedsy. Then work through the process of adjusting it in preparation for publication.
- This process is not capable of producing a 100%-compliant manuscript
… and you need a 100%-compliant manuscript to submit to publishers and agents …
- Missing: per page headers—
Lastname / Short Title / Page number—because CSS is not capable of doing this. Someday CSS will support this. We all eagerly away for margin at-rules to be finally supported (currently a w3c working draft spec.) - Missing: the seamless ability to port to
.docx. Some publishers and agents will accept a.pdf, but most in the industry require.docx. There are ways to automate generating.docxfiles, but it's not a piece of cake. Read more about that in README-structure-summary.md. - Missing: (Poetry) No 2nd page+ of poem continuation blocks.
Also check out the myriad of authoring platforms out there: Scrivener, Novlr, LivingWriter, Dabble, Ulysses, Storyist (Apple-only, blech!), Final Draft (for screenwriters), Quoll Writer (Windows-only and not sure if Quoll Writer can produce a manuscript), others.
Check out the example manuscripts in this repository in their original markdown and then as PDFs. Use one of the templates as a template for your own work. And if you are already familiar with converting markdown to HTML and then HTML to PDF then that should be enough to get you going.
(1) Copy one of .md templates and rename it. (2) Replace the text with your
contact information, your story, etc. (3) Preview it in HTML. (3b) Potentially
save it as an HTML file. And then (4) convert the document to PDF.
Step 2 is done with any editor: Joplin, VSCode, Ghostwriter, Xed, Vim, etc. Even Notepad if you like.
Step 3 is done natively with Joplin, VSCode, or the Chrome browser. Or converted to HTML with Pandoc.
Step 3b is done natively with VSCode or Pandoc
Step 4 is done natively from Markdown with Joplin or the Chrome browser, or From from HTML via a Chrome browser.
The process, with more detail . . .
Download this repository.
-
From the command line using
git:- Copy (clone) the repository:
git clone https://github.com/taw00/manuscript-css/ cd manuscript-css
- Copy (clone) the repository:
-
From the GitHub UI:
- browse to https://github.com/taw00/manuscript-css/
Code(big blue button) >Download zip- Unzip the
manuscript-css-main.zipfile. - Change that name to
manuscript-cssif you like. - `cd manuscript-css'
And if you own a webserver somewhere. Stick this repo in your /pub/ directory
so you can import it over the web.
- Look in the templates directory, and rename it to whatever makes sense to you (lastname-yourtitle.md is pretty standard).
- Open that markdown document in your favorite editor.
- Replace the templated content with yours
- Write your story, scene by scene. (Or if a poetry collection, poem by poem.)
Rendering to HTML for review or presentation and then to PDF.
(1) editing, (2) previewing, and then (3) rendering a PDF
If you use Joplin for your markdown editing, use
the application's built in previewer for the "convert to HTML" step. And then
later, if you so choose, you can directly produce a PDF (CTRL-SHIFT-E) from
within the application.
Click the
Toggle Editor Layoutbutton in the upper-right-hand corner of the application. There you have it. The HTML preview of the document. It's as accurate a representation as your browser can produce.
If you want the end result to be an HTML file on disk, the two best options that I know about are pan (see below) and the Joplin app (right-click your document, Export, HTML file). If I want to share an HTML version of my document, I personally like to use the Joplin Cloud publish functionality to skip straight to producing a publicly viewable manuscript.
(1) editing, (2) previewing, and then (2.5) exporting to HTML
A BIG CAVEAT WITH VSCODE: VSCode blocks importing (
@import) from the filesystem. If you want to use the previewer and renderer in VSCode, you will have to host themanuscript-cssfolder on the web somewhere. Or in the meantime, as of this writing, just use my instance:@import url("https://toddwarner.io/pub/css/manuscript/manuscript.css");That is not guaranteed to be a functional link forever though.
Install (CTRL-SHIFT-X) these extensions: Markdown All-in-One,
Markdown Preview Mermaid Support, Markdown Footnotes, and
Markdown Superscript.
To preview the HTML: CTRL-k release then v
To export to HTML on disk: CTRL-SHIFT-P and then
>Markdown All in One: Print current document to HTML. It will be saved, I
believe, in the same directory as the markdown document.
Side note. If you are Joplin user but also love VSCode, there is an excellent VSCode extension that enables it to plug into the Joplin application ecosystem and largely replace Joplin's editor (and some of the front end). It's rather excellent, though the @import caveat mentioned above is hugely annoying. For that, install the extension
joplin-vscode-pluginand follow the instructions for usage.
Step 2.5: converting a markdown file to an HTML file.
This requires you use the command line and to have Pandoc installed, https://pandoc.org/.
Edit the markdown document with your editor of choice. Then . . .
Convert your markdown file to HTML:
(In this example really only -V and --metadata are optional.)
pandoc -s -V lang=en --no-highlight -f markdown-native_divs+raw_html \
--metadata title="yourtitle" \
-o lastname.yourtitle.html lastname.yourtitle.md
-smeans standalone rendering-V lang=eninserts the correct locale info in the HTML head element. Changeento your locale.--no-highlightmeans to not do any syntax highlighting.-f markdown-native_divs+raw_htmltells pandoc to trust our markup and not "autofix" certain things (that then break our markdown).--metadata title="your title goes here"sets the HTML title.-o filename.htmlsets the output filename
Note, the filename format is just what I prefer.
Note there is a Pandoc limitation that so many folks forget. Pandoc doesn't do CSS. What this means is that converting from Mardown to HTML works just fine because Pandoc just passes along your CSS. But Markdown (or HTML) to most other formats will have all that fancy CSS just dropped and not translated.
markdown (2) previewing as HTML and then (3) exporting a PDF
Within Chrome, prep it for markdown rendering . . .
- Install: https://chrome.google.com/webstore/detail/markdown-viewer
- Click the puzzle-piece and pin the entension to the browser bar
- Click the M icon and turn on allowing opening local files. Reference: https://github.com/simov/markdown-viewer
Edit the markdown document with your editor of choice.
Then browser to that .md file and it should render it perfectly as an HTML
preview.
Finally, of course, if you so choose, you can directly produce a PDF:
CTRL-P > Save as PDF
The HTML preview will not be as clean as Joplin's or VSCode's, IMHO, but it is pretty darn good.
HTML file exported to PDF
If you produced an HTML file from Pandoc or VSCode, you open the file in the Chrome browser . . .
file:///fullpath-to-the-document/lastname.yourtitle.html
and then CTRL-P > Save as PDF. That easy.
Note1: Chrome-based browsers manage the fonts better for export to PDF. So, I recommend using one of them for review and then export to PDF. This is one of the few times I recommend Chrome over Firefox.
Note2, Though Pandoc can produce a PDF, Pandoc doesn't grok custom-CSS. Therefore its renderings will not be accurate. Joplin and your web browser do a far better job. Pandoc's HTML renderings are solid though since Markdown is really just a sping of HTML.
That's it! Congrats!
Questions? Comments? Post them in the Discussions section of this repository.
-todd
Nope. It's just the best application that I have found for this kind of work. IMHO.
The great majority of markdown editors (see a selection and my thoughts later in this document) are great at editing text. Many can also preview your work, but they are only particularly good at showing you a prettier version of the text and not a fully customized rendering. This is fine if you just want nice looking notes and things. But not fine if you want very specific looking notes and things. Generating a manuscript view of your document is a very specific look.
This is where the Joplin note-taking application rises above its peers. Yes, your notes and documents look nice out of the box, but you also have the full ability to customize the results to your hearts content using standard CSS. Joplin is also a great personal document-management platform. And it can sync to the cloud. And you can publish things to the cloud for anyone to view. And it is fully end-to-end encrypted. And it has a web-clipper (super handy!!!) and a mobile app. So, yes, I suppose I am a Joplin shill. But for all the right reasons.
But I also use other editors out there. I use Vim, Xed, Marktext, and sometimes Obsidian. I am sure you have your preferred interface. Install Pandoc and follow the steps above. It's not complicated.
- Tables
- I have also done no styling for images. If you want to add images to your document, you are on your own. For now. I'll probably play with that in the future.
- I have tested
manuscript.csswith only a couple markdown environments. Some editors change the look and feel of certain elements, so just be aware. Since I overload the purpose of Joplin when I draft, I had to create a set of CSS to squash all of its Joplinisms when I render the document. Let me know what you see out there in the wild. - Using this with HTML instead of markdown. Well, it should just work, I just haven't tried it. I mean, markdown, in the end, is really just HTML with a bit of varnish.
LibreOffice
I have included Libreoffice templates in this repository. Copy the templates
into the $HOME/Templates/ folder. (Look in Tools > Options, LibreOffice > Paths for your Templates fold location.)
Now, you are going to use Pandoc to generate a functional, but messy LibreOffice .odt document. Then you will create a fresh document in LibreOffice from one of the templates. And finally, you will cut and paste text from the messy document to the new document, adjusting formatting as needed. Not ideal, but it works and it goes faster than it sounds.
To generate that messy .odt file:
pandoc -o your-manuscript.odt your-manuscript.md
To create a nice clean fresh-from-a-template LibreOffice document:
- Open LibreOffice
File > New > Templates...and pick the appropriate template.- Remove most of the example text, though first make sure you understand what things are. These templates are templated as such because they closely match Google Docs import/export style names. Looking at all the styles, everything under "normal" represents everything in thed document: "normal" is the text and other random things. "Heading 1" is for part titles. "Heading 2" is for chapter titles. "Heading 6" is for dinkus markers and the -30- marker. You will have to figure out how to wedge everything else in if you did a bunch of fancy things.
- Either cut-and-paste blocks of text from the "messy .odt" (use
CTRL-SHIFT-V) to the new document. Or, after you get pretty good at this, you can find an appropriate spot and import the whole messy document in:Insert > Text from file. . . and then clean up the mess.
There is a guy out there who uses Pandoc's reference mechanism (templating) to convert markdown to .odt and .docx into a short story manuscript format. It's not the worst way of doing things, but I don't care for it. If you want to play around with it, check it out here.
Google Docs
Check out my Google Docs templates here.
You can get your document into Google Docs one of two ways: 1. port it to LibreOffice, generate a .odt and then import that into Google Docs. Or 2. you could create a new clean document from one of those templates and do the cut-and-paste shuffle as described earlier.
Note. Importing and explorting documents into and out of Google Docs is error-prone. Google Docs is not the best at this. Office 365 is probably much better, but I have never used it. One thing is for sure though, Google Docs can import and export .odt better than .docx. Often, Google Docs won't even recognize a legit .docx file.
Also, I recommend turning on document conversion:
Gear Icon > Settings > General > Convert UploadsFinally, I have not played with it a ton, but you can connect and use Zoho Writer from within Google Docs and it is a far more featureful application. And it can handle importing and exporting better than Google Docs itself.
- The one big missing feature is, as I mentioned above, support for a per-page
header with
LASTNAME / SHORT TITLE / PAGENUMBERin the upper-right-hand corner. If I can get that working (via JavaScript maybe?) I may be able to never leave markdown, even for submissions (assuming they accept PDF). I mention this again because it annoys me. - More options for the placement of
.m-facts.
- 0-draft: either in markdown or handwritten
- work-in-progress: markdown drafting via the Joplin desktop application https://joplinapp.org. (Joplin is a note-taking software application that also serves as an excellent general purpose markdown editor.)
- review by other: I periodic share drafts or portion of a drafts with critique partners, alpha readers, and beta readers. For this, I also use Joplin's excellent Joplin Cloud service which has a really convenient publish-to-the-web feature.
- submission for publication: I port my markdown over to LibreOffice writer. I
developed a manuscript template and it doesn't take me long to convert my
markdown to LibreOffice, do a final proofread, and then submit a
.docxfile.
- Joplin: I've already sung Joplin's praises. But it is, IMHO, the far superior application for developing text-heavy context. Joplin provides a WYSIWYG editor as well as a text editor. Its included text editor is modest, but it can open a "note" in any editor you want that can be called from the command line. Finally, it is the one and only editor here that can go from text markdown to HTML to PDF without using a separate tool.
- Obsidian: Obsidian is similar type of application as Joplin. It has a more modern vibe. I actually have used Obsidian and Joplin side-by-side for some time, but I keep going back to Joplin. Joplin is just a more complete solution. Obsidian is more useful as a Zettlekasten application for management of your ideas, thoughts, and mental bookmarks. It's pretty slick. Check it out. As a markdown editor, it's merely okay. But it too can open files for edit in a text editor of your choosing.
- GhostWriter: great editor. It previews manuscript-formatted markdown incorrectly, but exports to HTML just fine. It's a half solution. It also had writer-friendly features like focus mode, etc. Skip it's previewer. Edit with Ghostwriter, export to HTML, and preview in a browser. It saves you a step in that you don't have to use Pandoc directly. BUT! To export to HTML, it needs Pandoc installed.
- Marktext: Man, I really like this editor as a writer's editor. Super simple and distraction free.
- Bear and Typora: I heard good things about these, but I don't use any Apple products so, I have never tried them.
- All the minimalistic note-taking software applications out there—just avoid them. They are a waste of your time except to jot down ideas to be transferred later.
- Gnome Text Editor: a great just-enough-features lightweight text and code editor. It's my go-to GP editor.
- Xed: a great just-enough-features
lightweight text and code editor much like Gnome Text Editor (see above), but
with a slightly more dated interface. I use Xed all the time, if for no other
reason that
xedis faster to type thangnome-text-editor. Hmm, I should create an alias (digression). - Text Editor Chrome Web App and Firefox Extension: This is actually a rather nice bare-bones editor.
- Vim: Vim is hugely powerful and designed for hardcore
programmers. If you know what you are doing you can make it do anything, and
do it offers a far more efficiently editing experience (with some complexity
added) than the rest of these editors, including automating the preview in
HTML step. But Vim has a steep learning curve. I have used it for decades.
Vim is a terminal program, but it also has a graphical version:
gvim. This is my go-to GP editor for raw text editing of code, css, html, and sometimes markdown and text. - VSCode: A very
popular, somewhat-complicated, code editor. And very much like the
once-popular Atom editor. VSCode also has an excellent previewer and a great
Joplin plugin!
Unfortunately, you can't take advantage of @importing manuscript.css locally
using VSCode. It's security model disallows it. But you can leverage it if
you use
manuscript.cssvia an https connection. VSCode's Markdown All-in-One extension can export to HTML, negating a need to use Pandoc. Atom: DO NOT USE. The project has shut down Atom was a great general purpose code editor but was rather complicated to use. It's markdown capabilities were powerful but at the same time fell very short or our needs. Microsoft (who now owns the project) shut it down on December 7, 2022. I only list this here because it's on every markdown editor list out there. VS Code is essentially Atom's successor.
General manuscript formatting guidelines
Please note, again, that manuscript formatting is a loose standard and ultimately governed by to whomever you are submitting. For example, if a publishing house demands the typeface be Comic Sans, you format your manuscript in Comic Sans.
Here are some general guidelines.
- https://www.shunn.net/format/novel/
- https://graemeshimmin.com/manuscript-format-for-novel-submission/ A4!
- https://blog.reedsy.com/guide/book-manuscript-format/
- https://www.shunn.net/format/poetry/
- https://www.masterclass.com/articles/how-to-format-and-submit-your-poetry-manuscript
Check out the example manuscripts in this repository and I think how everything
works with manuscript.css becomes obvious.
Good luck. Now, quit fooling around on the internet and write something.
Copyright (c) Todd Warner [email protected] This work is licensed under Attribution 4.0 International. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/