Shrimple
a
**better**,
**cleaner**
Markdown alternative.
[Get it](https://code.qount25.dev/qount25/Shrimple).
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!](https://shrimple.qount25.dev)
idea: a link gets its URLs from
the footnote it's referring to.
Of course, you can also add a regular footnote
1
, 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](https://prismjs.com)
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:
Very similar are numbered lists:
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.
Notes start with a line which consists of one word in uppercase (no spaces) optionally followed by any punctuation sign — in this case it's ":". The following lines must be indented with 4 spaces. The word doesn't have to be "NOTES" and, instead, can be something like "SIDENOTE" or "ATTENTION". The word itself will be downcased and used in the output as html tag css class.
Notes may also contain empty lines (with no indentation), but an empty line must be surrounded by non-empty ones belonging to this note (and, thus, indented with 4 spaces) in order to be considered part of the note.
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.