The Goodnight Markdown Specification - Version 0.1.0
Goodnight Publishing
10 May 2025
Table of Contents
Reasoning
There are currently a number of tools for writing.
- MS Word Bloated. Includes unncecicary or distracting features and outputs documents that have a distinct and unplesant look to them. Libre Word alternatives suffer the same problems.
- Google Docs happens on Googles side. You lose everything if they lose everything, or if they decide they need more space. They use documents in Google Docs to train their AI models.
- LaTeX. Complicated and unncecicary for all but the people who are producing complicated and unncecicary works.
- Markdown. Simple and useful for general writing but does not include references. Has some features I would personally regard as unncecicary.
I was important, when designing Goodnight, to think what might be the responsibility of the parser, the stylesheet and the user. For example, although horizontal lines are almost always a common feature in Markdown flavors, I belive it is the responsibility of the stylesheet.
Features
Along with the features below, some features where removed:
- Line breaks have been removed.
- Horizontal rules have been removed.
I don't belive in line breaks and horizontal rules are the responsibility of the stylesheet.
Headings
Headings are prefixed with the # hastag character as with standard markdown. There must not be a space before the # character. This can go up to five hashtag "levels". For LaTeX, this is: section, subsection, subsubsection, paragraph and subparagraph. For HTML, although there are normaly six levels of heading (h1 - h6), the first is reserved for the title so "level one" translates to h2. Additionally, the title of the heading (lowercase and seperated by hyphens) is used as the anchor text for reference in the table of contents. For gemtext, there are normally no more than 3 levels, of which one is reserved for the title, so only 2 are used. In the case of gemtext, the table of contents will still refelect the sematic order of document up to the normal 5 levels. A space may or may not be put after the #. Inline formatting will be properly parsed. Inline references will be properly parsed.
Example:
## Goodnight!
In LaTeX:
\subsection{Goodnight!}
In HTML:
<h3 id="goodnight!">Goodnight!</h3>
In gemtext:
### Goodnight!
Links
Links look similar to how images are implemented in markdown, but instead of an exclaimation mark, = is used. This can only be done at the start of a line. There are also more feilds than that of images, these mean the following:
=[Caption][LaTeX link][HTML link][gemtext link] or... =[LaTeX link][HTML link][gemtext link] or... =[Caption][Universal link] or... =[Universal link]
This is because different formats might require different link locations. Format agnostic links are still possible for ease of writing or if the file in specific to one format.
Paragraphs
A paragraph is any line that does not start with one of the following: #-. or ``` or one of the macros such as [TOC]
Images
As in conventional markdown, images are represented with square backets, preceeded by an exclaimation mark. This must begin on the first character of a newline. The image caption is captured in the first set of square brackets, with the path to the image captured in the second. In LaTeX, this renders as an image centered in a figure enviroment with the figure caption contained in the first pair of brackets. In HTML this renders as an image in a <figure> tag, with a <figcaption> containing the caption. In gemtext this is simply a link to the path provided with the caption as the link text.
Example:
![Goodnight][images/goodnight.png]
In LaTeX:
\begin{figure}
\centering
\includegraphics[width=0.7\textwidth]{images/goodnight.png}
\caption{Goodnight}
\end{figure}
In HTML:
<figure> <img src='images/goodnight.png' /> <figcaption>Goodnight</figcaption> </figure>
In gemtext:
=> <images/goodnight.png> Goodnight (image)
Code
Inline code blocks can be used with the ` backtick character. In LaTeX this becomes \texttt{...}, in html this becomes <code>...</code> and in gemtext it is included as written. A bar character cannot currently be used in an inline code block.
Code blocks can be used with three backtick characters: ```. This sequence must start on the first character on a new line. This is parsed into the <pre> HTML tag, the verbatim LaTeX enviroment and the gemtext code block enviroment (also bookended by three backticks).
Block quotes
Block quotes are started with the tab character t. They can contain any other elements.
This is a paragraph within a blockquote
- This is a list element in a blockquote
Tabbed lines with a space between them are joined into one single blockquote. If two different blockquotes are needed next to each other, a backslash at the first character of a newline can split the two up.
This is parsed into the HTML quote tag, the LaTeX quote enviroment and the gemtext block quote enviroment (where every line is preceeeded by a > symbol).
Inline formatting
Bold styling is done with a single * character surrounding the bold text. This is parsed to \textbf and <b> respectively with inline formatting not supported in gemtext.
Italic styling is done with a single _ character surrounding the italicised text. This is parsed to \textit and <em> respectively with inline formatting not supported in gemtext.
Lists
In HTML and LaTeX, lists are parsed directly to list markup with no complications (enumerate, itemize and \item for LaTeX and <ol>, <ul> and <li> for HTML). In gemtext, both type of list item is included prefixed with a * character and no nesting is needed.
Ordered lists will work only with the period character. They are numbered by the browser in the case of HTML, or externally by the LaTeX compiler in the case of LaTeX. Gemtext does not support ordered lists so the parser numbers the list elements in plaintext. Ordered lists can be broken up by including a blank line between two lists.
Macros
To generate the title, table of contents and bibliography, the following macros can be used at the first character of a newline:
[META]generates the title block[TOC]generates the table of contents[REFS]generates the bibliography
In LaTeX, the title and bibliography are styled by the parser, rather than the native \maketitle or \printbibliography command. The table of contents is generated by the LaTeX compiler natively. In HTML and gemtext, the title, table of contents and references are all styled by the parser.
Note that in HTML, <hgroup> is used for a semantic title block and the <h1> tag is used for the title only and in gemtext the first heading level is used for the title only.
Metadata
The metadata format used is the YAML format. To generate the title, the standard LaTeX keys of "title", "author" and "date", should be used. If "style" is used, the parser will introduce the stylesheet with the relevant extension. For example, style: stylesheet will introduce stylesheet.css for html and stylesheet.sty for LaTeX.
Example:
--- title: The Goodnight Markdown Specification - Version 0.1.0 author: Goodnight Publishing additional_information: This is some additional information ---
Referencing
All referencing in Goodnight is APA 7th. Everything is the reference list is listed in the bibliography, even works not included in the text, so you are resposible for making sure this lines up with your work.
Each reference can happen anywhere in the text, begining with the ID for the reference. This ID can then be used in the body of the text to produce the inline reference. The text of the ID is arbitrary but can only contain alphanumeric characters. If "title" or "author" are used in square brackets directly after the inline id (for example [goodnight][author]) then that feild will be printed in the text. Following the ID, each on a new line, are a set of "keys" which describe the work.
Example:
[goodnight][author] ([goodnight][year]) writes "Each reference can happen anywhere in the text" \[goodnight] title: The Goodnight Markdown Specification - Version 0.1.0 author: Goodnight Publishing url: https://goodnight-publishing.co.uk
Becomes:
Goodnight Publishing (n.d.) writes "Each reference can happen anywhere in the text"
The keys are as follows:
author. The authors or entities behind the work seperated by the word "and". Wrap entity names in curly bracketstitleyear. "n.d." used if no year is given. (optional)publisher(optional)url(optional)journaltitle: Title of the book or journal the work is in (optional)issuetitle: Issue title of the book or journal the work is in (optional, must be used withjournaltitle)editor: Author of the book or journal the work is in. Should be formatted the same as "author". (optional, must be used withjournaltitle)volume: Volume of the book or journal the work is in. Example: "7th". (optional, must be used withjournaltitle)
Maths
Math mode has yet to be implemented.