This repository has been archived by the owner on Jun 27, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 4
/
index.html
236 lines (176 loc) · 11.8 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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
<!DOCTYPE html>
<html>
<head>
<title>Caltech Library's Digital Library Development Sandbox</title>
<link rel="stylesheet" href="/css/site.css">
</head>
<body>
<header>
<a href="http://library.caltech.edu"><img src="/assets/liblogo.gif" alt="Caltech Library logo"></a>
</header>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="index.html">README</a></li>
<li><a href="license.html">LICENSE</a></li>
<li><a href="install.html">INSTALL</a></li>
<li><a href="docs/">Documentation</a></li>
<li><a href="how-to/">HOW TO</a></li>
<li><a href="https://github.com/caltechlibrary/mkpage">Github</a></li>
</ul>
</nav>
<section>
<p><a href="https://www.repostatus.org/#active"><img src="https://www.repostatus.org/badges/latest/active.svg" alt="Project Status: Active – The project has reached a stable, usable state and is being actively developed." /></a></p>
<h1>mkpage</h1>
<p><em>mkpage</em> is a deconstructed, post modern, content management system for generating static websites.
It is suited to building sites hosted on services like GitHub Pages or Amazon’s S3. It is
comprised of a set of command line utilities that augment the standard suite of Unix/POSIX commands
available on most POSIX based operating systems (e.g. Linux, Mac OS X, Raspberry Pi and Windows systems that
have a port of Bash).</p>
<p><em>mkpage</em> can run on machines as small as a Raspberry Pi. Its small foot print and minimal
dependencies means installation usually boils down to copying the precompiled binaries to a bin directory
in your path. Precompiled binaries are available for Linux, Windows and Mac OS X running on Intel as
well as for the ARM7 versions of Raspbian running on Raspberry Pi. <em>mkpage</em> is built on Go’s text templates.
The template markup is similar to the <a href="https://mustache.github.io/">Mustache</a> and
<a href="http://handlebarsjs.com/">Handlebars</a>. It is also similar to <a href="https://gohugo.io">Hugo</a>’s template markup. <em>mkpage</em> has been easier for us to support when compared with
more established static site generators like <a href="https://jekyllrb.com/">Jekyll</a> <a href="https://gohugo.io">Hugo</a> and <a href="http://assemble.io/">Assemble</a>.</p>
<p><em>mkpage</em>’s minimalism turns into an advantage when you combine <em>mkpage</em> with the standard suite of text processing tools available under your typical Unix/POSIX like operating systems. This makes scripting a <em>mkpage</em> project using languages like Bash and Python relatively straight forward. Each <em>mkpage</em> utility is independent. You can use as few or as many as you like when you script your website creation process. You wind up with a workflow and build process that best fits your needs.</p>
<p>The following command line tools come with <em>mkpage</em></p>
<ul>
<li><a href="docs/mkpage.html">mkpage</a> – a single page renderer with support for Markdown, <a href="https://mmark.nl">Mmark</a>, <a href="https://fountain.io">Fountain</a>, JSON and Go text templates</li>
<li><a href="docs/mkslides.html">mkslides</a> – a HTML slide generator based on the approach in <em>mkpage</em></li>
<li><a href="docs/mkrss.html">mkrss</a> – an RSS feed generator for content authored in Markdown and rendered to HTML</li>
<li><a href="docs/sitemapper.html">sitemapper</a> – an XML Sitemap generator</li>
<li><a href="docs/frontmatter.html">frontmatter</a> – a front matter extractor</li>
<li><a href="docs/byline.html">byline</a> – a tool for extracting bylines from Markdown files</li>
<li><a href="docs/titleline.html">titleline</a> – a tool for extracting the first title (H1) in a Markdown document</li>
<li><a href="docs/reldocpath.html">reldocpath</a> – a relative path calculator, useful for pathing hrefs and src attributes in a website</li>
<li><a href="docs/ws.html">ws</a> – a fast, small, web server for site development or deployment</li>
<li><a href="docs/mkpongo.html">mkpongo</a> – a experimental version of mkpage using <a href="https://github.com/flosch/pongo2">Pongo2</a> style templates.</li>
</ul>
<h2>A quick tour</h2>
<p><em>mkpage</em> command accepts key value pairs and applies them to a Golang <a href="https://golang.org/pkg/text/template/">text/template</a>.<br>
The key side of a pair corresponds to the template element names that will be replaced in the render
version of the document. If a key was called “Content” the template element would look like <code>{{ .Content }}</code>.
The value of “Content” would replace <code>{{ .Content }}</code>. Go text/templates elements can do more than
that but the is the core idea. On the value side of the key/value pair you have strings of one of
four formats - plain text, markdown, <a href="https://fountain.io">fountain</a> and JSON. These four formatted strings can be explicit strings,
data from a file or content retrieved via a URL. Here’s a basic demonstration of sampling of capabilities
and integrating data from the <a href="http://weather.gov">NOAA weather website</a>.</p>
<h3>a basic template</h3>
<pre><code class="language-template"> {{ define "weather.tmpl" }}
Date: {{- .now}}
Hello {{.name -}},
The current weather is
{{index .weatherForecast.data.weather 0}}
Thank you
{{.signature}}
{{ end }}
</code></pre>
<p>To render the template above (i.e. <a href="examples/weather.tmpl">weather.tmpl</a>) is expecting values from various data sources.
This break down is as follows.</p>
<ul>
<li>“now” and “name” are explicit strings
<ul>
<li>“now” integrates getting data from the Unix <em>date</em> command</li>
</ul></li>
<li>“weatherForecast” comes from a URL which returns a JSON document
<ul>
<li>”.data.weather” is the path into the JSON document</li>
<li><em>index</em> is a function that lets us pull out the initial value in the array</li>
</ul></li>
<li>“signature” comes from a file in our local disc</li>
</ul>
<h3>the <em>mkpage</em> command</h3>
<p>Here is how we would express the key/value pairs on the command line.</p>
<pre><code class="language-shell"> mkpage "now=text:$(date)" \
"name=text:Little Frieda" \
"weather=http://forecast.weather.gov/MapClick.php?lat=13.47190933300044&lon=144.74977715100056&FcstType=json" \
signature=examples/signature.txt \
examples/weather.tmpl
</code></pre>
<p>Notice the two explicit strings are prefixed with “text:” (other possible formats are “markdown:”, “json:”).
Values without a prefix are assumed to be file paths. We see that in testdata/signature.txt. Likewise the
weather data is coming from a URL. <em>mkpage</em> distinguishes that by the prefixes “http://” and “https://”.
Since a HTTP response contains headers describing the content type (e.g. “Content-Type: text/markdown”) we
do not require any other prefix. Likewise a filename’s extension can give us an inference of the data format
it contains. “.json” is a JSON document, “.md” is a Markdown document and everything else is just plain text.</p>
<p>Since we are leveraging Go’s <a href="https://golang.org/pkg/text/template/">text/template</a> the template itself
can be more than a simple substitution. It can contain conditional expressions, ranges for data and even
include blocks from other templates.</p>
<h3>About Go text/template</h3>
<p><em>mkpage</em> template engine is the Go <a href="https://golang.org/pkg/text/template/">text/template</a> package. You can
get a feel for working with Go templates and <em>mkpage</em> by exploring <em>mkpage</em>’s <a href="how-to/">How To</a>. A good place
to start is <a href="how-to/the-basics.html">how to/the basics</a> and then proceed to <a href="how-to/one-element/">How To/One element</a>.</p>
<h3>companion utilities</h3>
<h4>mkpage</h4>
<p><em>mkpage</em> comes with some helper utilities that make scripting a deconstructed
content management system from Bash easier.</p>
<h4>mkslides</h4>
<p><em>mkslides</em> generates a set of HTML5 slides from a single Markdown file. It uses
the same template engine as <em>mkpage</em></p>
<h4>mkrss</h4>
<p><em>mkrss</em> will scan a directory tree for Markdown files and add each markdown file with
a corresponding HTML file to the RSS feed generated.</p>
<h4>frontmatter</h4>
<p><em>frontmatter</em> will extract a Markdown files’ front matter so you can
process it with another tool. When you used in conjunction with <em>mkpage</em>
you can render the same file into metadata about the file and
HTML output. This is handy if you’re using the front matter to build
up metadata in an HTML template or building a corpus JSON document
for use with browser side search engines like <a href="https://lunrjs.com">Lunrjs</a>.</p>
<h4>byline</h4>
<p><em>byline</em> will look inside a markdown file and return the first <em>byline</em> it finds
or an empty string if it finds none. The <em>byline</em> is identified with a regular
expression. This regular expression can be overridden with a command line option.</p>
<h4>titleline</h4>
<p><em>titleline</em> will look inside a markdown file and return the first h1 equivalent title
it finds or an empty string if it finds none.</p>
<h4>reldocpath</h4>
<p><em>reldocpath</em> is intended to simplify the calculation of relative
asset paths (e.g. common CSS files, images, feeds) when working from
a common project directory.</p>
<h5>Example</h5>
<p>You know the path from the source document to target document from the project root folder.</p>
<ul>
<li>Source is <em>course/week/01/readings.html</em><br>
</li>
<li>Target is <em>css/site.css</em>.</li>
</ul>
<p>In Bash this would look like–</p>
<pre><code class="language-shell"> # We know the paths relative to the project directory
DOC_PATH="course/week/01/readings.html"
CSS_PATH="css/site.css"
echo $(reldocpath $DOC_PATH $CSS_PATH)
</code></pre>
<p>the output would look like</p>
<pre><code class="language-shell"> ../../../css/site.css
</code></pre>
<h4>ws</h4>
<p><em>ws</em> is a simple static file web server. It is suitable for viewing your local copy
of your static website on your machine. It runs with minimal resources and by default
will serve content out to the URL <a href="http://localhost:8000">http://localhost:8000</a>. It can also be used to host
a static website and has run well on small Amazon virtual machines as well as Raspberry Pi
computers acting as local private network web servers.</p>
<h5>Example</h5>
<pre><code class="language-shell"> ws Sites/mysite.example.org
</code></pre>
<p>This would start the web server up listen for browser requests on <em><a href="http://localhost:8000">http://localhost:8000</a></em>.
The content viewable by your web browser would be the files inside the <em>Sites/mysite.example.org</em>
directory.</p>
<pre><code class="language-shell"> ws -url http://mysite.example.org:80 Sites/mysite.example.org
</code></pre>
<p>Assume the machine where you are running <em>ws</em> has the name mysite.example.org then your could
point your web browser at <em><a href="http://mysite.example.org">http://mysite.example.org</a></em> and see the web content you have in
<em>Site/mysite.example.org</em> directory.</p>
</section>
<footer>
<span><h1><A href="http://caltech.edu">Caltech</a></h1></span>
<span>© 2020 <a href="https://www.library.caltech.edu/copyright">Caltech library</a></span>
<address>1200 E California Blvd, Mail Code 1-32, Pasadena, CA 91125-3200</address>
<span>Phone: <a href="tel:+1-626-395-3405">(626)395-3405</a></span>
<span><a href="mailto:library@caltech.edu">Email Us</a></span>
<a class="cl-hide" href="sitemap.xml">Site Map</a>
</footer>
</body>
</html>