kursg(1)

bofc manual pages

kursg(1)


 

NAME

kursg - kurwinet site generator. Generates simple static webpages from markdown and html files.  

SYNOPSIS

kursg [options]  

OPTIONS

-h
print this help message and exit.
-i
<path> directory to process
-o
<path> output directory
-d
delete output directory before generating
 

DESCRIPTION

kursg is very simple static site generator. It's purpose is to create sites that focus on content rather than look or dynamic javascript features. Main strength of this program is that creating source for site is very easy, just create one simple control file and bunch of markdown or html and then run kursg on that directory and you're done.  

GENERATION RULES

BASIC USAGE

In the most basic usage program simply iterates through all markdown, html files and directories and for each file creates static site.

Consider following source tree with markdown files


    .
    ├── header.in
    ├── footer.in
    ├── index.in
    ├── index.md
    ├── sub1
    │   ├── page1.md
    │   └── page2.md
    ├── sub2
    │   └── page3.md
    └── sub3
        ├── page4.md
        ├── page5.md
        ├── page6.md
        └── sub4
            ├── page7.md
            └── page8.md

For such source, following structure of html files will be generated.


    .
    ├── index.html
    ├── sub1
    │   ├── page.html
    │   └── page2.html
    ├── sub1.html
    ├── sub2
    │   └── page3.html
    ├── sub2.html
    ├── sub3
    │   ├── page4.html
    │   ├── page5.html
    │   ├── page6.html
    │   ├── sub4
    │   │   ├── page7.html
    │   │   └── page8.html
    │   └── sub4.html
    └── sub3.html

Using above source tree and ./sub3/sub4/page7.md file following site will be generated


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+-------+-------+--------------------------------------+
    | index | page4 | page7 | <contents of page7.md file>          |
    | sub1  | page5 | sute8 |                                      |
    | sub2  | page6 |       |                                      |
    | sub3  | sub4  |       |                                      |
    +-------+-------+-------+--------------------------------------+
    | footer                                                       |
    +--------------------------------------------------------------+

Output directory structure will be same as input, so if program finds sub3/page4.md file in input, in output directory sub3/page4.html file will be created.

Menu is generated for each directory in path in cascade style. Each file or directory will have exactly one entry in menu based on directory structure. You can think of menu as of some kind of file system that presents directories and files. If file ./sub3/sub4/page7.md is parsed, program will generate links for all files in root directory ./, then sub3 and then for sub4. Each directory will have matching html file generated. This file will contain menu for all directories in path and some content based on options.

To better understand this behaviour let's follow parsing flow for file ./sub3/sub4/page7.md:

First header is generated from header.in file. Then we generate menu listing all files and directories in root directory


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+------------------------------------------------------+
    | index |
    | sub1  |
    | sub2  |
    | sub3  |
    +-------+

Then program goes to another directory in path, that is sub3, and its menu is appended next to first one. Generation rules for all menus are the same - a simple list of files and directories


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+-------+----------------------------------------------+
    | index | page4 |
    | sub1  | page5 |
    | sub2  | page6 |
    | sub3  | sub4  |
    +-------+-------+

By analogy, next directory is parsed, that is sub4 and we get


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+-------+-------+--------------------------------------+
    | sub1  | page4 | page7 |
    | sub2  | page5 | sute8 |
    | sub3  | page6 |       |
    | page0 | sub4  |       |
    +-------+-------+-------+

Finally, we detect that page7.md is a file, and we generate html from that file and we append it to the site.


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+-------+-------+--------------------------------------+
    | sub1  | page4 | page7 | <contents of page7.md file>          |
    | sub2  | page5 | sute8 |                                      |
    | sub3  | page6 |       |                                      |
    | page0 | sub4  |       |                                      |
    +-------+-------+-------+--------------------------------------+

And last but not least, footer is appended and we get complete site.


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+-------+-------+--------------------------------------+
    | index | page4 | page7 | <contents of page7.md file>          |
    | sub1  | page5 | sute8 |                                      |
    | sub2  | page6 |       |                                      |
    | sub3  | sub4  |       |                                      |
    +-------+-------+-------+--------------------------------------+
    | footer                                                       |
    +--------------------------------------------------------------+

MATCHING FILES

Matching file is a file which has same name (excluding extension) as directory in the same folder. ie:


    .
    ├── sub1.md
    └── sub1
        └── page1.md

Normally, kursg would automatically generate sub1.html page with content of page1.md. By providing matching file, sub1.html will be generated with contents of sub1.md file. page1.md will still be reachable from sub1.html file from menu.

DIRECTORIES WITHOUT FILES

If needed, directories can contain only other directories and no markdown or html files. If that is the case, kursg will try to find any file it could use as content-file.

Consider following source tree:


    .
    ├── index.md
    ├── sub1
    │   ├── page1.md
    │   └── sub2
    │       └── sub3
    └── sub2
        ├── sub5
        ├── sub6
        │   └── sub8
        │       └── page2.md
        └── sub7
            └── page3.md

With such tree main page will look like this:


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+------------------------------------------------------+
    | index | <contents of index.md file>                          |
    | sub1  |                                                      |
    | sub2  |                                                      |
    +-------+------------------------------------------------------+
    | footer                                                       |
    +--------------------------------------------------------------+

Now when opening site sub1 we'll see


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+-------+----------------------------------------------+
    | index | page1 | <contents of page1.md file >                 |
    | sub1  |       |                                              |
    | sub2  |       |                                              |
    +-------+-------+----------------------------------------------+
    | footer                                                       |
    +--------------------------------------------------------------+

Note that sub2 and sub3 were not included in menu, that is because menu entry is not generated if there are no useful files that could be used as content, and genereting empty links has no real value.

If we open sub2 page, we'll see this


    +--------------------------------------------------------------+
    | header                                                       |
    +-------+-------+-------+-------+------------------------------+
    | index | sub6  | sub8  | page2 | <contents of page2.md file>  |
    | sub1  | sub7  |       |       |                              |
    | sub2  |       |       |       |                              |
    +-------+-------+-------+-------+------------------------------+
    | footer                                                       |
    +--------------------------------------------------------------+

Entry for sub5 was not generated, because it is empty. sub6, altough empty, was generated because there was at least one usable file somewhere in the directories below. sub6, sub8 and page2 will render same page.

LINKS RULES
Links can both relative or absolute. Absolute links are not recommended, as such links will not be reachable when site is viewed directly via files, and not by www server. Links should always point to generated html files.
 

META FIELDS

All markdown, html or .kursg-info files can contain some meta fields to tune how to generate that file. All fields are optionally.

Since all files have different syntax, each file type need to define these fields differently. Syntax with examples for each filetype is

markdown
[kursg-meta]: # (<field-name>: <field-value>)

    [kursg-meta]: # (title: about me)
    [kursg-meta]: # (order: 3)
html
<!-- [kursg-meta:<field-name>] <field-value> -->

    <!-- [kursg-meta:title] about me -->
    <!-- [kursg-meta:order] 3 -->
.kursg-info file
<field-name>: <field-value>

    title: about me
    order: 3
title
Name of the entry in menu that will link to file. If this is not set, file name will be used instead
order
Order in which menu entry will appear in menu. Lower value means higher priority and entry will be put earlier in <li>
index (only available in .kursg-info file)
If directory has no matching file (see .kursg-info in CONTROL FILES for more information about what is a matching file) this file will be used to generate content when generating site for this directory. If this option is not passed, first found file (alphabetically) will be used instead. If no files are inside folder, kursg will try to find proper file recursively. File must be in the same directory as .kursg-info so entry filename.md is allowed by directory/filename.md is invalid.
 

CONTROL FILES

Control files are used to tune how site will be generated. Only index.in file is mandatory

index.in (mandatory)
Mandatory file, defines most basic information like title of style. Format of the file is 'key="value"' (note there is no space between key, = and "value"). Following keys are supported

in_title
Site title, will be put in <title> tag in every html page
in_description
Site description, will be put in <meta name="description"> tag in every html page
in_keywords
Site keywords, will be put in <meta name="keywords"> tag in every html page
in_author
Author of the page, will be put in <meta name="author"> tag in every html page
in_lang
Site language in ISO 639-1 format (like en, pl, it, jp)
in_pygment
Pygment variant (color set) to use for generated code blocks (~~~ tag in markdown)
in_style
What style to use to generate page
header.in (optional)
Pure html code that will be put right after <body> tag between <div id="header"> and </div> in every generated page
footer.in (optional)
Pure html code that will be put right before </body> tag between <div id="footer"> and </div> in every generated page
.kursg-ignore (optional)
If this file is present, that directory and all directories down the path will be ignored and pages won't be generated for them. Consider following directory tree
    .
    ├── d1
    │   ├── .kursg-ignore
    │   ├── d3
    │   │   └──d4
    │   └── d5
    └── d2

In that example, d1 contains .kursg-ignore and thus will be ignored. But d3, d4 and d5 all contains .kursg-ignore in path above then, and thus will be ignored too.
.kursg-info (optional)
Tune how to generate html for the directory if directory does not have matching source file - that means folder exist but file with the same name (excluding extension) does not. Consider following example:
    .
    ├── sub1
    │   └── .kursg-info
    ├── sub1.md
    └── sub2
        └── .kursg-info

In this example sub1 has matching source file sub1.md and sub1/.kursg-info file will be ignored, as all information on how to generate access to sub1 directory will be read from sub1.md file. Check META FIELDS to see accepted fields.
custom.css (optional)
If this file is present, it will be added to generated site after css from in_style, so any css option can be overwritten or extended here
static.in (optional)
This is list of files or directories that should be copied into static directory in output. Directories are copied in recursive mode. Pathsshould be relative to input path.

bofc.pl

18 January 2018 (v1.0.0)

kursg(1)