This repository has been archived by the owner on Mar 12, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
176 lines (161 loc) · 10.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Everything you need to know to get started with Jeknil.">
<link rel="icon" type="image/png" sizes="16x16" href="assets/favicons/16.png">
<link rel="icon" type="image/png" sizes="32x32" href="assets/favicons/32.png">
<link rel="icon" type="image/png" sizes="180x180" href="assets/favicons/180.png">
<link rel="icon" type="image/png" sizes="192x192" href="assets/favicons/192.png">
<link rel="icon" type="image/png" sizes="512x512" href="assets/favicons/512.png">
<link rel="stylesheet" href="assets/font/epilogue.css" type="text/css" charset="utf-8" />
<link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<script defer src="assets/prismjs/prism.js"></script>
<link rel="stylesheet" href="assets/prismjs/prism.css">
<style>
body {
background-color: #2B2B2B;
font-family: 'Epilogue';
color: #D2D2D2;
margin: 2em 20% 2em 20%;
}
code {font-family: 'Fira Code';}
.banner {width: 75%;}
a:link, a:visited {color: #FFCC00;}
a:hover, a:active {color: #FF9900;}
.date {color: #171717;}
h1 {color: #FFCC00;}
code {color: #FFCC00;}
</style>
<title>Jeknil's README</title>
</head>
<body>
<span class="date"><i>Last updated on 2020-07-09</i></span><br><br>
<img src="assets/jeknil_banner.png" alt="Jeknil Banner" title="Jeknil Banner" class="banner"/>
<p><a href="https://github.com/knaque/nimble-tag-2"><img src="https://raw.githubusercontent.com/knaque/nimble-tag-2/master/nimble-tag-2.png" alt="nimble" /></a></p>
<p><a href="https://nimble.directory/pkg/stalinsort"><img src="https://nimble.directory/ci/badges/jeknil/version.svg" alt="version" /></a>
<a href="https://github.com/Knaque/stalinsort"><img src="https://nimble.directory/ci/badges/jeknil/nimdevel/status.svg" alt="install test" /></a>
<a href="https://nimble.directory/docs/stalinsort//stalinsort.html"><img src="https://nimble.directory/ci/badges/jeknil/nimdevel/docstatus.svg" alt="doc build" /></a></p>
<p>Jeknil is a dead-simple static blog post generator designed to be as easy as
possible to use. No dependencies, no unnecessary deployment process, just a
single executable that turns Markdown into HTML.</p>
<p>If you're viewing this at <a href="https://knaque.dev/jeknil">knaque.dev/jeknil</a>, then
you're looking at Jeknil own README turned into nice HTML, with a bit of manual
editing since it's a bit hard to talk about Jeknil's variables when they're
being replaced, as will be explained shortly.
<a href="https://github.com/knaque/jeknil">GitHub Repository</a></p>
<h1>Installation</h1>
<p>Make sure you have both the Nim compiler and the Nimble package manager
installed via <code>nim -v</code> and <code>nimble -v</code> respectively. If you don't, both can be
installed simultaneously <a href="https://nim-lang.org/install.html">here</a>. Once both
are installed, just do <code>nimble install jeknil</code>, and wait a moment for it to
compile. Once it's done, <code>jeknil</code> will be available on your command line.</p>
<h2>Building from source</h2>
<p>Follow the same instructions as above to ensure you have both the Nim compiler
and Nimble package manager. Once you do, clone this repository, then
navigate to the clone's folder. <code>nimble install</code> will automatically download
required libraries, build Jeknil, and install it to your system. Alternatively,
you can also compile Jeknil with <code>nim c -d:release ./src/jeknil.nim</code>, but this
method requires both manually installing dependencies and manually adding the
executable to the PATH, so it's not recommended.</p>
<h1>Usage</h1>
<p><code>jeknil [--options] [file(s)]</code></p>
<p>Run <code>jeknil</code> without any arguments to display help information, including an
list of each flag and its function.</p>
<h1>Setup guide</h1>
<h2>template.html</h2>
<p>Whenever Jeknil is run, it checks for a file called <code>template.html</code> in the
working directory. This file describes the format that should be used for posts.
This is primarily intended for specifying custom <code><head></code> data, but can include
any valid HTML.</p>
<p>If you don't want to store your template in your working directory, the default
behavior can be overwritten with the <code>-t:<dir></code> flag.
(i.e. <code>jeknil -t:./some_dir</code>)</p>
<p>The key part of <code>template.html</code> is variables. Variabes are a word surrounded by
curly brackets, and are used to tell Jeknil where to place different data.
The currently available variables are:</p>
<ul>
<li><code>{title}</code> - The title of your post, as defined in its Header*.</li>
<li><code>{description}</code> - The description of your post, as defined in its Header.</li>
<li><code>{content}</code> - The actual content of your post, as written in Markdown.</li>
<li><code>{date}</code> - The date the post was generated in the <code>YYYY-MM-DD</code> format.</li>
</ul>
<p>*<em>Headers will be explained shortly.</em></p>
<p>Here is an example of a typical template, including a favicon set, external
fonts, and a code block formatter.</p>
<pre><code class="language-html"><!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Everything you need to know to get started with Jeknil.">
<link rel="icon" type="image/png" sizes="16x16" href="../favicons/16.png">
<link rel="icon" type="image/png" sizes="32x32" href="../favicons/32.png">
<link rel="icon" type="image/png" sizes="180x180" href="../favicons/180.png">
<link rel="icon" type="image/png" sizes="192x192" href="../favicons/192.png">
<link rel="icon" type="image/png" sizes="512x512" href="../favicons/512.png">
<link rel="stylesheet" href="https://indestructibletype.com/fonts/Jost.css" type="text/css" charset="utf-8" />
<link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="./assets/prism.css">
<script src="./assets/prism.js"></script>
<link rel="stylesheet" href="./assets/style.css">
<title>knaque's blog - Jeknil's README</title>
</head>
<body>
<span class="date"><i>last updated on 2020-07-09</i></span> - <a href="../index.html">homepage</a>
{content}
</body>
</html>
</code></pre>
<p>Once you've made a template, you can test it with <code>jeknil -e</code>. This will
generate the file <code>template-example_<date>.html</code> with some example content, allowing you
to quickly ensure everything is displaying as it should.</p>
<h2>Writing posts</h2>
<h3>The Header</h3>
<p>Now it's time to write a post. The only Jeknil-unique part of this process is
the <em>Header</em>, which is very similar to Jekyll's <em>Front Matter</em>. The Header
starts with <code>~!</code> and ends with <code>!~</code>, or alternatively with standard HTML
comments. (Jeknil uses whichever it finds first. This is because using these
symbols more than once causes a parsing error.) At the moment, the Header is
used to define the <code>{title}</code> and <code>{description}</code> variables, therefore a standard
Header would be:</p>
<pre><code>~!
title: "An example title"
description: "An example description."
!~
</code></pre>
<p>You <em>must</em> put each in quotes in order for it to be parsed properly. A Header
can be anywhere in the document, but generally it's best to put it at the
beginning.</p>
<p>Everything else is standard Markdown, and most things should be supported. You
can even include HTML inside your markdown, allowing you to use things such
as Classes and IDs to improve formatting. See this README's top banner for an
example:</p>
<pre><code class="language-markdown">An HTML `<img>` with a class!
<img src="https://knaque.dev/ext/jeknil/jeknil_banner.png" alt="Jeknil Banner" title="Jeknil Banner" class="banner"/>
Then some Markdown images...
[](https://github.com/knaque/nimble-tag-2)
And finally, plain Markdown text...
</code></pre>
<p>Even the Template variables from before (except for <code>{content}</code>) can be used in
your Markdown.</p>
<h3>Code Syntax Highlighting</h3>
<p>If you put the language just after the opening of a large code block
(i.e.```nim), a class for that language will automatically be added
(<code>language-nim</code> in this case), meaning nothing extra is required to use a code
formatter; just include a one in your <code>template.html</code> and specify the language
in your Markdown.</p>
<h2>Generating the result</h2>
<p>Once you're done writing your post, simply run <code>jeknil some-post.md</code> and Jeknil
will output the generated file in your current working directory, with the
format <code><header title>_YYYY-MM-DD.html</code> for the file name.</p>
<p>If you don't want save your generated posts in your working directory, the
default behavior can be overwritten with the <code>-o:<dir></code> flag.
(i.e. <code>jeknil -o:./some_dir</code>)</p>
<p>Jeknil can also generate multiple posts at once, simply by listing every post
separated by a space, i.e. (<code>jeknil post1.md post2.md etc.md</code>)</p>
<hr />
<h3>If this documentation could be improved in any way, don't hesitate to <a href="https://github.com/Knaque/jeknil/issues/new">raise a GitHub issue</a> describing your thoughts.</h3>
</body>
</html>