a better, cleaner Markdown alternative.

Shrimple

a better, cleaner Markdown alternative. Get it.

This is a Shrimple document. It's written in such a way that it looks clean and readable both as a text document, but also when rendered into HTML.

Installation & Usage

You'll need a Go compiler to compile it first:

go build

Then run it like this:

cat README | ./shrimple -s -w > README.html

The -s or --default-css flag adds a default css to the HTML output and -w or --wrap flag wraps the page up in HTML to make a complete document. If you're looking to generate output and insert into your own website one way or another, you're not going to need those tags.

To see all available options type: ./shrimple --help

Links and Footnotes

Links are made to be clean-looking as well. Instead of polluting the source document with inline URLs (which can be long and can mess up readability) we instead use a very shrimple! idea: a link gets its URLs from the footnote it's referring to.

Of course, you can also add a regular footnote ¹ , in which case the little link with the number next to the word will lead you to the footnote section.

Code

Let's start with code blocks. Look at the example below: even though there's an empty line between the two if blocks, it'll still be one singular block of code:

if err != nil {
    return -1
}

if err == nil {
    return 1
}

Blocks of code must be indented with 6 spaces, which, when rendered, will be trimmed, but the extra spaces after the first 6 are kept. The first line of the code block which starts with ### Go is optional, but it adds an HTML-class to the code block tag, which, when used with Prism.js code highlighter, will result in correct code highlighting for a particular language.

We can also have inline code, such as fmt.Println("this is inline code")

Lists

Shrimple also allows you to create numbered and bullet lists. For example, here's a list with bullet points:

• Lists must be indented two spaces to the right
• Each item may or may not be separated from the previous one by an empty line.
• If a list item is long, you can easily put the content on the next line. In that case, the subsequent lines must all be indented with 4 spaces to be aligned with the first line.

Very similar are numbered lists:

1. Indentation is the same — two spaces.
2. Subsequent items may be numbered normally (unlike Markdown, where they all have to be "1").
3. Subsequent lines in any given numbered list item must be aligned by the fullstop character "." on the first line.
4. Numbers don't have to be consequtive, but they will be normalized to be consequtive. It just werks!

Two types of headers

Headers are allowed to be of two level types: "h1" and "h2". The level is determined by the "thickness" of the underscore line, where === is for "h1" and --- is for "h2". One important thing about headers: the line following the actual header, regardless of the time, must always be at least 3 characters long (it is a hardcoded rule) or the line above will not be rendered as a header.

Parse & render dictionaries

This is one of the most powerful features of Shrimple. Instead of polluting your original document with various kinds of strange characters or HTML, you just write your text and when need to highlight some occurrences of particular words or expressions, you define it using Parse & Render dictionaries. Take a look at the two files: parse_dict and render_dict in the repository's root directory and then look at the example in the next paragraph:

This paragraph is an example of parse and render dictionaries. Note that the word1 and word2 are underlined, and word3 and expression with some spaces in it are green. But there's no additional markup for these words in the source Shrimple document. They're simply picked up based on the parse and render dictionaries.

To instruct Shrimple to make use of parse and render dictionaries, use the -p and the -r cli-arguments ("p" for parse, and "r" for render):

./shrimple ... -p path/to/parse_dict -r path/to/render_dict

Generating static website

One of the goals of Shrimple always was to be able to generate documentation pages. This his made possible by Shrimple's static site generator. It will take a directory of source files (written in Shrimple format), convert each file into an HTML-document and output it all into another directory. Each page will optionally contain a menu and a previous/next navigation links at the bottom.

Let's see how it works. Suppose you have the following directory structure:

StaticSite
|
'--
   StaticSite
   |
   1_Part_One
   |        |
   |        001_chapter_one 
   |        002_chapter_two 
   |        003_chapter_three 
   |
   2_Part_Two 
   |        |
   |        001_chapter_four
   |        002_chapter_five
   |
   3_chapter_six
   |
   4_chapter_seven

Entries 1_Part_One and 2_Part_Two are directories. The rest of it are files. When file is named the same as the directory it contains, it'll become index.html after the static site is generated. The numbers at the beginning of directories and file names are there to ensure correct order which is necessary to know to be able generate navigation and menu links.

The same file structure is provided in the examples/StaticSite directory for your convenience. To generate the static website use the following command:

./shrimple -s -g -n -m examples/StaticSite StaticSite_out

and see what's inside StaticSite_out directory. If changes are made to some files and then you run the same command again, Shrimple will only generate the files which need to be generated.

The options provided are the following:

• -g or --generate-site tells Shrimple that we want to generate static website from the source directory.
• -s is already known to you — it adds a default stylesheet, but you can specify your custom one with -c or --css
• -n tells static site generator to add previous/next navigation links to the bottom of each page.
• -m also adds nicely nested menu containing links to all of the generated pages.

All links in menu and navigation work if you simply open your page with File - Open in your browser and don't require a server to be usable.

1. Footnotes are basically numbered list items.
2. Except you can reference them by putting [n] anywhere in the document (see above)
3. Or you can create links with them without polluting the document itself by saying '-&rt; link [4]'
4. https://shrimple.qount25.dev
5. https://prismjs.com
6. https://code.qount25.dev/qount25/Shrimple