09.05.2015

Margen

Margen is an html generator from Markdown format. All these pages are generated just by Margen by Stanislav Marencik.
Why just Margen?

  • As simple as possible
  • Easy to install. Unpack margen.zip and it should work
  • Based on Markdown. If not satisfied then you can switch to other engine but articles in Markdown stay
  • No database - moving to other webhosting is simple because you only move files
  • Rather quick

Installation

Just only download margen.zip and unpack to your webhosting. When unpacking to the root of your webhosting then you needn't configure anything, It should work out of the box.
Note: it's also a working demo

Configuration

.htaccess

It must redirect all requests for Markdown file to the same file which takes path to Markdown file as parameter.

RewriteEngine On
RewriteBase /

RewriteRule ^.*\.(md|markdown|mdown|mkdn|mkd|mdwn|mdtxt|mdtext) /convertMarkdown.php [QSA,L]

By default the file has name convertMarkdown.php and we can consider it to be an engine.
Note: When you put convertMarkdown.php file to deeper location than root then you also must correct its path.

Engine convertMarkdown.php

$ROOT_DIR = getcwd();
$DEFAULT_TEMPLATE_FILE = "templates/templateMd.html";
include_once 'lib/convertLib.inc';
printHtml($ROOT_DIR.$_SERVER["REQUEST_URI"],
        array("defaultTemplateFile"=>$DEFAULT_TEMPLATE_FILE),
        array("breaksEnabled"=>true,
              "markupEscaped"=>true,
              "urlsLinked"=>false));

There are several configuration variables at the top of php:

  • $ROOT_DIR - rule is that $ROOT_DIR + REQUEST_URI must give local path to Markdown file. getCwd() usually does this job. When engine not in root but one level deeper then getcwd()."/.." is the way how to get to root directory
  • $DEFAULT_TEMPLATE_FILE - relative path to default template file. It's relative against this engine script. It's used when not specified special template for page.

printHtml
Is a main and the only function that user should use.
Arguments:

  • Path to markdown file on filesystem
  • Configuration of templating. It's array where keys are:
    • defaultTemplateFile - see above
    • dateTimeFormat - format to be used in date function of php. Default is d.m.Y. For example to show year, month, date, hour, minute, the format would be Y-m-d H:i
  • Configuration of conversion using Parsedown library which converts Markdown to HTML. It's array where keys are:
    • breaksEnabled - line feeds are also new lines in html
    • markupEscaped - you can allow html tags in Markdown or supress
    • urlsLinked - see Parsedown doc

Template file

Is a file that contains placeholders which are replaced by data.
Example:

template.html
<html>
<head>
<link rel="stylesheet" type="text/css" href="${templateDirPath}/css/layout.css">
</head>
<body>
  ${content}<br/>
  <!-- footer -->
  <!-- :begin{possiblyUnpopulatedDisplay}<script>
  document.body.style.background = "yellow url('img_tree.png') no-repeat right top";
  </script>:end{possiblyUnpopulatedDisplay} -->
</body>
</html>

Where directory structure is e.g.:

-www
    -template.html
    -css
        -layout.css
    -pages
        -page1.md

Simple placeholders
Some data related to page can be inserted into template (or Markdown page - experimental feature) to certain place. By default, all placeholders are:

  • populated by data taken from page. Note, also empty data are data to be inserted.
  • used default value when data not set
  • removed when data are missing and default value not exists

format:
${variable[:default]}
variable is a variable to be used for population
default is default value to be generated when variable is not set. Default is not applied for empty values (string without characters).

Special (reserved, prepopulated by engine) variables:

  • content - markdown body converted to html
  • templateDirPath - relative path from current page to template file. Use this variable to point to all resources which are referenced from template.
  • date - update date of file

Escaping placeholders
Sometimes we wold like to show text like ${variable1} but such text wouldn't be rendered because not existing data remove placeholders. Escaping is done by ${} inserted between $ and opening curly bracket.
Example:

$${}{variable1}

Comment based markers
It's useful for larger parts to be rendered conditionally. Body between markers is rendered when variable is set. The value of variable is not important.
format:

<!-- :begin{markerVariable}BODY:end{markerVariable} -->

Text is uncommented only when markerVariable is set

Page

Page contain header followed by body using Markdown syntax. Format is:

---
var1: value1
var2: value2
...
varN: valueN
---
Body

The header is optional. Following is also valid page but without any custom variables:

Body

The header elements can contain empty values:

---
date:
---
This page has empty string as date (not update date of file)

In this case we override prepopulated variable date by empty string because in template the placeholder may be present but not always we want date to be shown.

Other example of page:

---
date: 2015-03-31
title: Great Ship
---
was made in 1918...

For template file:

template.html
<html><body><h1>${title}</h1><div style="float: right">${date}</div>${content}</body></html>