LEARN SHANTY

A MARKUP LANGUAGE FOR WRITING E-BOOKS

Saturday Night at Sea by Thomas Dibdin, an illustration of sailors singing a sea shanty.
Saturday Night at Sea by Thomas Dibdin, taken from Wikimedia Commons.

OVERVIEW

SHANTY is a markup language that makes writing e-books easier. With minimal markup, anything from a short story to a novel can be easily converted into my Nantucket e-book platform.

Nantucket is an e-book platform that is mobile-friendly, and will work in any modern browser. It includes interactive features like note-taking, dark mode, bookmarking, and audiobook integration.

Here's an example of a Nantucket e-book.

To publish a Nantucket e-book, simply format your text with the Shanty syntax. You can use any text editor you wish: Notepad, Word, Google Docs, Pages, OpenOffice.org, you name it. Since Shanty is plain-text, it's lightweight and future-proof. Then, run it through my text-parser, Gam, and you'll receive a Nantucket E-Book in HTML format.

If you're a writer, Shanty makes it a snap to convert your text files into a Nantucket e-book. Eliminate the tedious task of adding HMTL tags to a document, and spend your opportunity costs on more writing!

TABLE OF CONTENTS


BASICS

ADDING A TITLE AND AUTHOR

To add a title and author to your e-book, add the following lines:

Title and Subtitle as they appear in markup Title and Subtitle as they appear after rendering From November in America by Nicholas Bernhard

ADDING CHAPTERS

Breaking down your e-book into chapters is easy. Place # before the name of each chapter.

If your chapter has a subtitle, use ## and put it on the next line.

The program will look for these symbols, and use them to build your table of contents.

Chapters as they appear in markup Chapters as they appear after rendering

Make sure every chapter title is unique!

Hyperlinks are what make digital documents truly powerful. To add a link to a paragraph, use the following syntax:

Links will open in a new tab, unless it's a link within the e-book itself, or a download link.

If you add an id to your link, make sure there are no spaces.

To specify the download option, type download.

You may want to give an id to a specific bit of text, which you can then link to. To do this, use the following syntax:

You should use the footnote functionality to add a footnote.

EXTRAS

BREAKS

To add a section break, also known as a dinkus, just add four asterisks, ****, on a new line.

Breaks as they appear in markup Breaks as they appear after rendering From Then A Skeleton Popped Out by Nicholas Bernhard

To add an empty space, add the following on a new line:

To use an image as a break, check out the section on adding an image.

BOLD AND ITALICIZED TEXT

To add bold text to your e-book, put two asterisks (**) on either side of the word(s).

To add italicized text to your e-book, put one asterisk (*) on either side of the word(s).

Italicized text in markup Italicized text as it appears after rendering From November in America by Nicholas Bernhard

Want to make text bold and italicized? Use three asterisks!

TEXT-ALIGN

Nantucket will default to justified paragraphs: each line has the same width.

If you want to align the text a different way, put the following lines at the beginning of your paragraphs:

Text-align markup Specially-aligned text after rendering

SUB-TITLES

To add a sub-title to your book, just add a !!SUBTITLE line to the beginning of your text:

Subtitle as it appears in markup Subtitle as it appears in markup From November in America by Nicholas Bernhard

SPECIAL CREDITS

The program will automatically credit the e-book as "By author's name."

If you want to specify a different credit, use a !!CREDIT line.

Special credits as they appear in markup Special credits as they appear after rendering

DATES AND LOCATIONS

You may want to end your piece with some information on when and where you wrote it. This helps ground your work in a specific time and place. To do so, use the following format:

The date must be either YYYY-MM-DD, YYYY-MM, or YYYY.

Location and Date as they appear in markup Location and Date as they appear after rendering

Nice. Just like Stephen King!

The location and date are both optional, you can use either, neither, or both.

These will always be placed towards the end of your document.

DEDICATIONS

To add a dedication to your e-book, add the following line:

Dedication as it appears in markup Dedication as it appears after rendering From November in America by Nicholas Bernhard

QUOTES AND EPIGRAPHS

An epigraph is a quote at the beginning of your book that sets the tone, or provides the context, for the rest of the work.

To add an epigraph, or any other special quote, use the following lines:

Blockquote as it appears in markup Blockquote as it appears after rendering From Sweet Relief by Nicholas Bernhard

FOOTNOTES

Please be advised that the footnotes feature is janky AF, Tom.

If you absolutely must add a footnote, here's the steps:

1) Include the notation <FN> for your footnote.

2) At the end of the paragraph containing the footnote, include the following:

Footnotes will appear in the Footnotes section of the e-book. Each footnote includes a link back to the original paragraph.

As long as the order of the <FN>'s is the same as the @@FN's, each footnote link will match with the intended footnote text. This is made easier by adding the footnote text directly below the corresponding paragraph.

You should use the hyperlink functionality to link to other parts of the document.

THE END

To end your prose piece with The End, add the following on a new line:

LYRICS AND POETRY

If you need to add a few lines of a song or poetry to your e-book, preface each line with a grave accent (`), like this:

To add a bit of space between verses, preface the last line of each verse with two grave accents (``):

Poetry as it appears in markup Poetry as it appears in markup From November in America by Nicholas Bernhard

Since much of a poem's meaning comes from its presentation, I understand that this may be insufficient. If a poem has to be presented a certain way, check out the later sections on customization.

COMMENTS

If you start a line with two slashes, (//) it will be ignored by the parser.

BACK TO HOME


ADDING ART TO YOUR E-BOOK

Since our media environment is almost entirely visual, it is recommended that you include images in your e-books.

For all images, remember to choose an image resolution and compression that minimizes file size, and maximizes quality. A bit of experimenting is a great help.

For freedom's sake, please use the open formats PNG and SVG for your images. Open formats respect your freedoms as an author, and the freedoms of your readers.

If you do not value freedom, and only care about technical considerations, here are the general guidelines for which file types to use:

The official Nantucket E-Book website will only accept JPG, PNG, GIF, and SVG.

Please be very reserved about using moving images in your e-book, including GIFs and SVGs. Part of the joy of reading is the escape from doo-dads and flashing lights. Moving GIFs can also be hard on bandwidth. However, if they aren't abused, moving images can add a certain effect to your e-book. For example, some subtle movement in an illustration might create atmosphere for a horror story. I only ask for you to be smart about it.

I highly encourage use of SVG. SVG images have small file sizes, and will scale to any screen size. The audio player and menu icons for the Nantucket e-book platform are SVG images that I created by hand in my text editor, after designing them with paper and pencil. SVGs also support motion and interactivity, though be careful with those features. It's a very, very powerful format, and since it's an open standard, it's free to experiment with. Free and open-source vector graphics software programs are available online for creating SVG images.

Host your image files locally. As a matter of nettiquette, avoid linking to an image on someone else's site without the site's approval, even if the image's licensing and copyright status allow it (for example, a public domain image on Wikimedia Commons).

NOTE: for information how to add paths to your image files, see the section on file paths.

ADDING A COVER IMAGE

Can you say pizzaz? If you want to add a cover image to your e-book, add the following line:

Markup for a cover image

The cover image will always come first in the e-book.

If you want to include a description of the cover image, and the artist's name, include the following lines at the beginning of your document:

Cover art metadata as it appears in markup Cover art description as it appears in markup From Then A Skeleton Popped Out by Nicholas Bernhard

!!COVERART will add a credit to your title section, and to the Credits section at the end of the e-book.

!!COVERDESC will add title and alt text to your image, which is helpful for accessibility, and makes your e-book more attractive to search engines.

For cover images, I recommend settings their dimensions to five units wide by eight units tall. This is an aspect ratio of 1.6. For e-books on the official Nantucket E-Book website, these dimensions are mandatory.

ADDING ILLUSTRATIONS

You can add an indefinite number of illustrations to your e-book. To add an illustration, include the following line in your text:

Only the :source attribute is required, and if :caption is used, it must come last.

The file path to your illustration cannot contain any spaces.

Markup for illustrations How illustrations appear after rendering From November in America by Nicholas Bernhard

If your book has one illustrator, you may want to credit them at the beginning. To do so, use the following line at the beginning of your text:

Markup for metadata about illustrator Illustrator markup after rendering From Sweet Relief by Nicholas Bernhard

ADDING AN IMAGE

If you want to add a plain ol' image to your e-book, use the following syntax:

The file path to your illustration cannot contain any spaces.

The :ornament attribute is optional, and lets the program know if the image is being used in place of a line break.

The :title attribute is optional, though it is always recommended to descriptions of images on web pages. If you do make use of the :title attribute, make sure it comes after :source.

Images will be centered on the page. A small image is an excellent way to break up a text, and makes for a good alternative to the **** break described earlier. You will need to add your own styling to ensure the image displays at the intended size on various devices.

Markup for plain images Plain images after rendering From Then A Skeleton Popped Out by Nicholas Bernhard

BACK TO HOME


ADDING AN AUDIOBOOK

One of the most powerful features of the Nantucket E-Book format is the ability to have a book's text, and an audio version, together. Adding audiobooks to your e-book is much the same as adding an illustration.

PREPARING THE AUDIO SECTION

Before adding audio files to your e-book, start by adding an !!AUDIO tag at the beginning of your text:

Neither parameter is required. If no copyright information is specified for the audiobook, the e-book will say so.

If a background image is specified, it will be blurred and brightened to separate it from the foreground elements. If no background is specified, the program will default to a plain seashell background, like the rest of the e-book.

NOTE: for information how to adding the path to your audiobook background, see the section on file paths.

ADDING AUDIO FILES

Any number of audio files can be included.

Audiobooks should be in one of two formats: MP3 or OGG/Vorbis. Both are open formats, meaning anyone can create a file in that format without paying royalties. MP3 is supported by all current major browsers, while OGG may not work in Apple's Safari browser.

Audiobooks on the official Nantucket E-Book website may use either OGG or MP3.

Longer works, such as novels, should break the audiobook into several short audio files.

Add the following line to your text to include an audio file:

The file path to your illustration cannot contain any spaces.

NOTE: for information how to add paths to your audio files, see the section on file paths.

BACK TO HOME


METADATA AND SEARCH ENGINE OPTIMIZATION

This section covers things that will make your website look more appealing to search engines, plus copyright info.

Most of this information will be placed in the <head> section of the HTML document, where readers won't see it, but search engines can.

COPYRIGHT INFORMATION

It's a very, very good idea to include the copyright info for your e-book, even if it's 100% public domain. This furthers the legal protection for your e-book, and lets the reader know how they can share it.

To add copyright info, add the following line to the beginning of your document:

Markup for copyright info on a book Copyright info after rendering From November in America by Nicholas Bernhard

If your work is public domain, use:

Markup for designating a Nantucket E-Book's text as Public Domain A public-domain symbol in a Nantucket E-Book

This will put a strikethrough on the copyright symbol.

SEARCH KEYWORDS

Search engines will look for keywords associated with a web page. For example, if your work is about baseball, you'd better include the keyword 'baseball.'

On the offical Nantucket E-Book website, readers may use these keywords to search for e-books as well.

To include keywords for your e-book, include !!KEYWORDS at the beginning of your text, followed by all the necessary keywords.

Try to think of words people might search for, where your e-book would be a good result.

Markup for adding keywords to a Nantucket E-Book From November in America by Nicholas Bernhard

PAGE DESCRIPTIONS

Search engines will also look for descriptions of web pages. Use this part to include a brief summary of your e-book that search engines will see.

Markup for giving a description to a Nantucket E-Book From November in America by Nicholas Bernhard

PAGE LANGUAGE

Lastly, search engines will try to figure out which language your e-book is in. While the search engine can make an educated guess, make it easy, and just tell it what the language is.

Markup for specifying the language for a Nantucket E-Book

If you don't include this line, the program will automatically default to English, "EN"

Here are the language codes for the top ten most-spoken languages, according to Wikipedia:

Chinese ZH
Spanish ES
English EN
Hindi HI
Bengali BN
Portuguese PT
Russian RU
Japanese JP
Punjabi PA
Marathi MR

BACK TO HOME


MONETIZING YOUR E-BOOK

You may want to include some way for people to financially support your work. You can include a call-to-action at the end of your page. To do so, include the following line:

Markup for adding crowdfunding information to a Nantucket E-Book Crowdfunding information for a Nantucket E-Book, after rendering From The Nantucket E-Book Platform by Nicholas Bernhard

Don't forget to include a link to your monetization site.

LISTING SUPPORTERS

At the end of your e-book, you may want to recognize the people who have supported your book through crowdfunding platforms.

Shanty currently allows you to import a membership report from Patreon. You may do so using the following steps:

1) In your Patreon account, export the Membership Report as a CSV file. This CSV file will be downloaded to your computer.

2) Open the file in either a text editor (Notepad, Gedit, et al) or by dragging it into Google Chrome.

3) Select all the text (Ctrl + a), and then copy it (Ctrl + c).

4) In your Shanty document, create the following two tags on separate lines: @@DONORSTART and @@DONOREND. Paste your copied text between these two tags.

It should look like this:

The list of Patrons from Patreon will be sorted into their tiers, starting with the most-expensive tier and moving down from there.

BACK TO HOME


CUSTOMIZATION

REMOVING TABLE OF CONTENTS FOR SMALL E-BOOKS

The Nantucket E-Book format includes three tables of contents:

The first one is within the document itself. This one is ideal for accessibility, since it can be easily accessed with the TAB key on your keyboard. It also gives first-time readers a sense of the structure of your e-book, and its contents, just like a table of contents should.

The second one is intended for mobile users, and is a full-screen window which is accessed from the menu.

The last one is intended for desktop users. It is a drop-down list that can be accessed from the menu.

If your e-book is small, like a short story, for example, it may not make sense to include the first one. To remove it, just add the following line to the beginning of your text:

LINKING TO AN E-BOOK MENU

If you have more than one e-book, you may have a web page where your readers can see all of them.

You may want to include a link to that page in your tables of contents. To do so, include the following line at the beginning of your text:

If you have set your e-book's mode to !!MODE main, as described in the section on adding file paths, you do not need to specify a menu.

Markup for linking to a main menu From The Nantucket E-Book Platform by Nicholas Bernhard

ADDING CUSTOM HTML TO YOUR E-BOOK

To add custom HTML to your e-book, use the following:

If you don't include the @@HTMLEND, the earth will crash into the sun.

Custom HTML would be useful if there your text requires some extra-special formatting. You may use the HTML <PRE> tag to preserve line spacing for a stylized poem.

In the example below, I have used custom HTML, and the PRE tag to maintain the original formatting of the Mouse's poem, from Alice's Adventures in Wonderland.

ADDING ADDITIONAL STYLESHEETS

With custom HTML comes custom CSS. If you would like to link a custom stylesheet to your e-book, include the following line at the beginning of your text:

ADDING CUSTOM FAVICONS

A favicon is a very small image that represents a web page. It is usually displayed on the tab of a desktop browser, or on the new window of a mobile browser:

The program will automatically use the Nantucket E-Books favicon, as seen on the top of this page.

The default favicon for a Nantucket E-Book

If you would like to replace it with your own favicon, include the following line at the beginning of your text:

ADDING PATHS TO YOUR FILES, AND USING "MAIN" MODE

If your Nantucket e-book includes any illustrations, audiobooks, or additonal stylesheets, you will need to specify where those files are located.

You may use either absolute or relative links where needed. If you are unfamiliar with the concept of absolute/relative for HTML, please check out this page on the subject from W3Schools .

The text-parser, Gam, assumes the following folder structure, which is the one the official site uses:

If you are hosting Nantucket E-Books on your own website, you must either set up your folders like this, or modify the necessary file paths to meet your needs.

If you are using this folder structure, I recommend setting up your own folder like the example below.

If you organize your Nantucket E-Books this way, you can simplify your life. Just put the following line at the beginning of your e-book:

Now, when you need to link to an audiobook file, illustration, or a stylesheet, all you need to do is provide the name of the file. The text-parser will fill in the rest!

For example, instead of typing ./assets/BOOK_ONE/images/illustration_01.jpg, you can specify !!MODE main, and just type illustration_01.jpg.

BACK TO HOME


FAVORITES

This is a more technical feature that you may include with your e-book. It is included for e-books published on the official Nantucket E-Book site, but requires more set-up if you are publishing to your own site.

It is possible to include a "FAVORITES" button in the menu. This button allows the reader to save a list of their favorite e-books into the local storage of their device's browser.

If you have a web page listing all your e-books, it is possible have this page highlight all of a user's favorited books.

Because this feature uses local storage, the information is more secure than if it were stored on a server.

First, you must create a unique keyword for your e-book. NOTE: all e-books published on the official Nantucket E-Books site will require a special keyword.

Second, you must create a name for your list of favorite e-books. If someone hits the favorite button for your e-book, this specifies where it should be saved.

If you are publishing to the Nantucket E-Book website, you must put nantucketFavorites as the name of your list. If you are writing in !!MODE main, this will be added automatically.

If you are publishing to your own website, you may have a page listing all your e-books. You can then write a simple JavaScript program to access this list, and have the user's favorite e-books listed or highlighted. Much of the necessary code may be found in the file nantucketCode.js on this website.

BACK TO HOME


EXAMPLES

I have included links to the Nantucket e-books used as examples in this document, plus the original plain-text files. You may also download them for your review.

All books by Nicholas Bernhard.

BACK TO HOME


CONTRIBUTE AND SUPPORT

The Nantucket E-Book project is the result of many, many hours of work, with the goal of providing the very best experience for my readers. If you would like to support these efforts, there are two ways to do so:

First, you can contribute to the project at GitHub.com/NDHF.

Second, you can support my work on Patreon. Your voluntary financial support will allow me to create the novels and short stories I'll release on Nantucket, as well as make improvements to the platform itself.


UPDATE LOG


LICENSING AND COPYRIGHT

Text © 2020 NDH Ltd.


CONTACT

Questions? Comments? Suggestions? You may e-mail me at Nicholas[at]NDHFilms[the Warner sister][com]

BACK TO HOME