$ namac --help
Usage: namac [args] [file1] [file2] [file3] [...]
Converts .nama markdown files, according to the syntax, to HTML5 .html or XHTML 1.0 Strict .xhtml files and lists them in a "directory.(x)html".
Options:
--help, --h or --?: displays this.
--version or --v: displays the version number.
--manual-directory or --manual_directory: resets to the directory.html according to the files just compiled, according to the order listed in the arguments.
--append-directory or --append_directory: appends to an existing directory.html.
--alphabetize-directory or --alphabetize_directory: alphabetizes an already existing or commanded to exist directory.html.
--html5: set output file to be HTML5.
--xhtml: set output file to be XHTML 1.0 Strict.
--outpute: Print out and write without the header or <body>.
--template: Takes template file and puts directory where {directory} is and content where {content} is.
So, the most basic "namac" file would be something like this:
title: first test
content {
case(hello) {
text {
I exist!
}
}
}
You could then save this as test.nama
and run namac --xhtml test.nama
, it will then convert it to XHTML.
To set a CSS script you could do namac --xhtml --style whatever.css test.nama
.
Now let's take a look at those basic components:
The 1st line, title: first test
, sets the <title>
for the XHTML, it's rather self-explanatory.
The 2nd line content {
essentially opens the body of the document, it's analogous to <body>
in XHTML.
The 3rd line case(hello) {
opens a "case" and sets its title line to be "hello".
The 4th line text {
opens a thing inside the case where you would usually write text, it is supposed to display as a rectangle of sorts.
The 5th line I exist!
is just text that you would write. This could also be XHTML or whatever, since it would transfer over, so it would say <i>I exist!</i>
. Also, it is automatically surrounded with <p>
and </p>
in XHTML, which can be turned off with !nlp
("!" meaning opposite or "no", new line paragraph).
Lines 6-8 are just closing curly brackets ending each element (ie </div>
).
First, let's define a template
file:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-type" content="application/xhtml+xml;charset=utf-8"/>
{title}
<link rel="stylesheet" href="whatever.css"/>
</head>
<body>
<div class="directory_nav">
<h3><i>Test</i></h3>
{directory}
</div>
{content}
<a href="namac/index.xhtml">Powered by NAMAC!</a>
</body>
</html>
This is essentially an XHTML file, but with 3 placeholders.
{title}
, which is where the title goes.
{directory}
, which we will define in a moment.
And finally {content}
which you can guess (it's everything from the .nama
file).
Second, let's define an example directory
:
somefile
howto
stuff/index
These will all have .xhtml
appended to them assuming --xhtml
is specified.
Obviously, they go where {directory}
goes in the template file.
Thirdly, let us define a webography
file. Webography is essentially bibliography and can be used as such:
T: smthiread
L: https://example.com/whatever.xhtml
N: Something I Read
D: 2019
T: anthrthngiread
L: https://example.com/sowhat.xhtml
N: Another Thing I Read
D: 2020
T:
means title (should be something quick to type), L:
is link/url, N:
is name (of the document/thing/source), D:
is date.
Finally, our .nama
file:
title: first test
!nlp
content {
case(hello)(https://example.com) {
text {
<b>I exist!</b>${smthiread}${anthrthngiread}
<br/>
I use {https://example.com}{example} as an example a lot.
{img/someimg.ff}{A random image in the farbfeld format}
{{img/someimg.ff}{This is a caption.}}
}
sources {
{footnotes}
}
}
}
Compile this with namac --xhtml --template test.nama
.
Let's go over what's new.
First off in case(hello)(https://example.com) {
there is a
link, which makes the title clickable. Note: if the case title has
spaces in it, the ID will have it's spaces replaced with underscores
(this is for XHTML adherence).
In <b>I exist!</b>${smthiread}${anthrthngiread}
the <b>I exist!</b>
part is just XHTML, the ${smthiread}${anthrthngiread}
part references the listings inside the webography
file. They show up as [1] and [2] (<sup><a href="#s1">[1]</a></sup><sup><a href="#s2">[2]</a></sup>
in XHTML), and are listed in {footnotes}
.
The <br/>
, which is just straight up XHTML.
{https://example.com}{example}
is a link with an optional name after it, {https://example.com}
would display just the link without a set name.
{img/someimg.ff}{A random image in the farbfeld format}
just like the link, except it's an image, as denoted be img/
(so yeah, you gotta have an img dir for this to work). Note: No browser that I am aware of supports .ff images, but here's to hoping.
{{img/someimg.ff}{This is a caption.}}
just like the other image, except this one is an actual box that shows up, assuming you have the proper CSS.
sources {
is another element opener.
{footnotes}
is where references are listed, for example "1. Something I Read, 2019 https://example.com/whatever.xhtml" (<li
id="s1" value="1">Something I Read, 2019 <a
href="https://example.com/whatever.xhtml">https://example.com/whatever.xhtml</a></li>
in XHTML).
Hopefully this guide helps you in using NAMAC. Or at least is useful to me as reference later, lol!