a better, cleaner Markdown alternative.

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 🔥

if err == nil 🔥

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.