Since all pages in MarkdownMaster CMS are simply plain text markdown files, writing content is as easy as writing a text file. In addition to all the basic syntaxes available in Markdown, there are a number of additional format options provided to simplify web authoring.
Different themes will support different content types, but pages are pretty
ubiquitous, and those content files are stored in the pages directory of the site root.
Blog themes will often use posts and authors as well,
for publishing blog articles (differentiated from just content pages), and author information.
To create a new page or post, just create a new .md text file within the desired
directory or copy an existing file or template. Nested directories ARE supported,
but common practices advise against nesting too deeply.
A common usage (especially for posts), is to group files by date published to better organize them, otherwise you will end up with a mess of files and assets.
The following directory structure examples will all provide the same automatic date string parsing from the URL.
# All posts are just in the root directory
- posts/
|- 2021-01-02-something.md
# Group posts by year, include month and day in the filename
- posts/
|- 2021/
|- 01-02-something.md
# Group posts by year, month, then day (probably excessive)
- posts/
|- 2021/
|- 01
|- 02
|- something.md
# Group posts by year and month, include day in filename
- posts/
|- 2021-01/
|- 02-something.md
HTML pages have a number of meta attributes that are used to describe the page to search engines and other tools. This goes outside the scope of basic markdown, but is supported in MarkdownMaster CMS via YAML front matter.
This metadata conforms to the
standard YAML specification
markup at the beginning of each file inside --- blocks.
---
title: Authoring Pages
author: Charlie Powell
tags: [Howto, Markdown, Authoring]
---
Note, it's important that the very first line is ---.
If the first line in the file is not ---, the YAML front matter will not be parsed
and this metadata will be considered part of the body.
To define a list of tags, wrap the tags with [ ... ] or list them on each line with a - prefix,
for example these two will provide the same results:
tags: [Howto, Markdown, Authoring]
tags:
- Howto
- Markdown
- Authoring
For images and URLs where extra information may be needed, it is often beneficial to break them out into the various important tag.
banner:
src: images/page_banner.jpg
alt: A banner image featuring something
call_to_action:
href: https://mysite.tld
title: Check Out My Cool Thing!
IMPORTANT, when tags are defined with a src or href key,
the value is auto-mapped based on the location of the file.
Example: if image.src is set to media/some_image.jpg in a file located at pages/some-page.md
on https://mysite.tld, that value will get auto-resolved to https://mysite.tld/pages/media/some_image.jpg.
If the value is fully resolved already, it will not be modified.
If the value starts with /, it is assumed to be at the root of the website, and just the URL is prepended.
| Attribute | Description |
|---|---|
| layout | An alternative layout template for rendering this file |
| title | Title to use for H1 and on listing pages |
| seotitle | Browser title to set when viewing the page |
| excerpt | Short excerpt or description of this page to display on listing pages |
| description | Description of this page to use for SEO purposes |
| date | Date this article was published |
| author | Name or alias of the author of this page |
| tags | Comma-separated list of tags for the content on this page |
| image | Fully resolve or relative path to preview image of this page |
DO NOT USE THESE! These are reserved for internal use only, but are available for use in your templates.
| Attribute | Description |
|---|---|
| body | The raw markdown content of this page |
| bodyLoaded | The rendered HTML content of this page |
| config | The configuration object for this page |
| content | The rendered HTML content of this page |
| name | The filename of this page |
| permalink | The permalink of this page |
| type | The type of content this is (page, post, etc) |
| url | The URL of this page |
Themes will support additional parameters; consult the documentation for the installed theme for more information about specific attributes that may be supported.
By default, page headers (H1 elements) are rendered within the layout template for content based off metadata, so the inclusion of one is not necessary.
---
title: My Page
---
# My Page
...
This example will produce the following result because the page title is effectively defined twice:
<h1>My Page</h1>
<h1>My Page</h1>
Since this is a markdown content system, markdown syntax is used for writing the articles.
Refer to the
official markdown syntax guide
for a refresher on details.
Images are supported within both the image:... metadata and from within article content. These images can either be fully resolved or relatively resolved (relative to the file you are editing).
Referencing images relative to the base file works because the browser will make the request
relative to that file. Top-level paths (starting with /) and absolute requests
(https://...) paths are also supported.
As part of the extended Markdown syntax supported in this platform, custom attributes can be added to various elements.
To use HTML attributes, append {...} to the end of the line with the HTML tags inside.
As some examples:
Short paragraph with class="center" added
This is a short example paragraph {.center}
Longer and multi-line paragraphs also support custom attributes.
These can be added _after_ the last line, without a blank space between.
{.center}
This link will have a title and target set.
Since both paragraphs and links support extended attributes, try to ensure
no space between the link and curly brace.
[Go Search](https://www.duckduckgo.com){title="Search for something" target=_blank}
This image will have a border
{style="border:5px solid pink;"}
Below is a list of attributes and shorthand versions, but ANY HTML ATTRIBUTE is supported.
| Attribute | Description | Example |
|---|---|---|
| "." prefix | Shorthand for class=... | {.center} |
| "#" prefix | Shorthand for id=... | {#myid} |
| style | CSS style attributes | {style="border:5px solid pink;"} |
| title | Title attribute | {title="My Title"} |
| target | Target attribute | {target=_blank} |
| data-* | Data attributes | {data-foo="bar"} |