~kungtotte/dtt

cd1252a8f9cff6cd2c78d951565badeb03cdab02 — Thomas Landin 7 months ago 3d7d09d
Add scdoc man-page file for docs

Also make a nimble task for running scdoc over the man page
3 files changed, 73 insertions(+), 0 deletions(-)

M .gitignore
A doc/dtt.1.scd
M dtt.nimble
M .gitignore => .gitignore +1 -0
@@ 3,3 3,4 @@ templates/*
output/*
config.cfg
content/*
doc/*.1

A doc/dtt.1.scd => doc/dtt.1.scd +69 -0
@@ 0,0 1,69 @@
dtt(1)

# NAME

dtt - A simple static site generator

# SYNOPSIS

*dtt* _init_ [DIR]

Write markdown

*dtt* _build_

# DESCRIPTION

The dtt tool is used to initialize a simple directory structure with a set of
functional and decent looking templates, after which you write markdown files
inside of the /content/ directory and optionally dump any static assets there as
well (images, html files, etc.).

After you run *dtt* _build_ it will hoover up anything inside /content/ and do one
of two things: if it's a markdown file it will turn it into html using the
mustache templating system, if it's any other kind of file it gets copied
straight across to the /output/ folder maintaining its original directory tree.

# USAGE

In order to be convenient *dtt* will make some educated guesses as to how to
handle your markdown files. It differentiates between a _page_ and a _post_ to
begin with; a page is any single page like an "about" page or an "index" page,
whereas a post is in the style of a blog post with a slug, a date it was posted
etc. A _page_ will just dump the markdown content pretty much as-is between the
header and footer templates, but a _post_ uses a blog-style template with
article sections to work well with screen readers and such.

A blog collection is available in the *mustache* template in the variable name
{{blog_posts}}, use that with the {{# syntax from *mustache* to list blog posts
on a page. It defaults to listing five posts but this can be changed by passing
a number to the *dtt* _build_ command. It's sorted with the newest at the top.

For now *dtt* only supports Commonmark Markdown with no extras at all such as
frontmatter.

## RULES

So let's go through the rules that you can use to manage your content and make
your life easier.

- A page uses page.mustache by default, and a post uses post.mustache.
- A page will use <pagename>.mustache if it exists.
- Any markdown inside one of the following directories is considered a post:
  blog, blogs, post, posts, articles, journal, journals
- Any markdown file starting with a YYYY-MM-DD string is considered a post.
- The title of a post is its filename minus any YYYY-MM-DD, dash/underscore, and
  extension.
- If no YYYY-MM-DD part of the filename is supplied it will read the creation
  date of the file and use that as the post's date.
- All pages are linked in the menu at the top.
- No posts are linked in the menu at the top.

# SEE ALSO

*mustache*(5)

# AUTHORS

Maintained by Thomas Landin <thomas@landin.xyz>. Up to date sources can be found
at https://git.sr.ht/~kungtotte/dtt

M dtt.nimble => dtt.nimble +3 -0
@@ 16,3 16,6 @@ requires "nim >= 1.0.4"
requires "markdown >= 0.8"
requires "docopt >= 0.6"
requires "mustache >= 0.2"

task make_doc, "Generate man page(s)":
  exec "scdoc < doc/dtt.1.scd > doc/dtt.1"