DIY CMS Docs

Documentation for DC

Base on this: https://docs.bearblog.dev/

Why DC?

Let a hundred blogging tools bloom; let a hundred schools of thought blog.

-- With apologies to Mao Zedong

The idea behind DC is encourage you to build, host and manage your own blog rather use one of the common free or paid for blogging services. In addition if it breaks your dependence on the big social media companies, all the better.

Why yet another blogging tool? Because the more independent tools the more freedom of expression there is and the more ways of thinking are encouraged.

DC is not a service. It is an imperfect blogging tool. It is not intended for those who want to get started with their blog right now. Rather it is designed for those who are willing to get their hands covered in cyber dirt. You don't need to have any coding knowledge to use this blogging software. If you follow the manual, it will work. You will though need a good dose of patience mixed with dollop of perseverance. Things will go wrong and you will have to figure out how.

If this is not you, perhaps you should try one of these alternative independent online blogging services:

• Bear Blog
• PIKA
• micro.blog

Table of Contents

1. Installation Guide
   1. Getting started
2. User Guide
   1. Site structure
      1. Folders
      2. Files
   2. File processing
   3. File structure
      1. Front Matter
      2. Content
   4. Menus
   5. Metadata
3. References

Installation Guide

Getting started

This tutorial is intended to set up a new blog with as little fuss as possible. It does so by making full use of GitHub. This includes hosting your site on GitHub Pages, under a custom domain name if desired.

First of all sign up for a GitHub account.

Next make a copy of the DC code by forking the DC repository.

Now explore GitHub a little. The GitHub docs are very comprehensive. Being comfortable writing content and editing configuration files will be helpful, but this can also be learned. The GitHub Writing guide is maybe a good place to start for those new to GitHub.

User Guide

Site tructure

Folders

Files

File processing

All content is stored in Markdown file, such as home.md. Only files with the extension .md are processed by the engine. All other file types are ignored unless they are static simply files to be copied.

Each .md file is converted to an index.html file. This file is placed in a folder with the same path and name as the .md file, unless specified otherwise in the Front Matter configuration for the file using the "permalink" attribute.

For example the file:

/posts/2023/summmer.md

would generated a file:

/posts/2023/summmer/index.html

which would be accessible using the URL:

/posts/2023/summmer/

And a file:

/pages/home.md

With the following front matter attribute:

permalink: /

Would generate file a here:

/index.html

Which would be accessible using this URL:

/

TO DO: explain slug "permalink": "//" as in pages.json.

File structure

All Markdown files, whether posts or pages have two main parts.

Firstly, a Front Matter part, which contains the configuration details for the file and is always at the beginning of the file.

Secondly, the rest of the file which contains the content.

Front Matter

The Front Matter section of the file has a specific structure which must be followed.

Firstly it always starts and ends with the line: ---.

Secondly it contains attribute / value pairs, one per line, eg: title: Welcome to my blog. The order of the attributes within the Front Matter is not important.

If the attribute contains a list of values, it would be spread over multiple lines, eg:

tags:
- post
- travel
- photo 

The Front Matter of a typical post might therefore look something like this:

---
title: Happy New Year
date: 2025-01-01 08:00:00
tags:
- celebration
- new year
- photo
---

DC understands the following Front Matter attributes. Any other attributes will be ignored.

Note: you do not need to enclose the value in quotes in the Front Matter section.

Content

In DC all content is written using GitHub's implementation of Markdown.

Note that Markdown can also contain HTML. So any tags for which there is no Markdown equivalent can be written in HTML.

A typical Markdown content file might therefore look something like this:

---
title: Happy New Year
date: 2025-01-01 08:00:00
tags:
- celebration
- new year
- photo
---

## Welcome

This is first blog post, I hope you enjoy this site.

<blockquote>Doing It Yourself Rocks!</blockquote>

Archives

Archives are lists of all the posts matching a specific tag.

They use the following Front Matter.

---
title: Coding 
pagination:
  data: web
  alias: posts

---

data is tag name to include in the archive.

Menus

Menus can be defined for the header and footer. This is done in the file "_data/menus.yaml". The syntax of this file is a little more complicated as it is written in YAML.

Learn more about the YAML syntax here.

As an example this file menus.yaml file for a site with two menus. A header and a footer menu:

- name: header
  items:
    - title: Home
      link: /home/
    - title: About
      link: /about/
    - title: Blog
      link: /blog/
    - title: /walking
      link: /walking/
      pre: 'and '
    - title: dog 🐕‍🦺
      link: /tagging/angie/
      pre: 'the '
      post: '. '
- name: footer
  items:
    - title: RSS
      link: /feed/
      class: ally-statement
    - title: Accessibility
      link: /accessibility/
    - title: Site info
      link: /my-site/

Metadata

Metadata for the site can be defined and is stored in the file "_data/metadata.yaml".

This is an example the metadata.yaml file for a basic site:

title: Robin's
url: https://www.robin.is/
urlShort: robin.is
language: en
description: Setup and host your own independent blog
startYear: 2025
relMe: https://github.com/robindotis/
gitHubRepo: https://github.com/robindotis/robin.is/
theme: sky
feed:
  subtitle: Setup and host your own independent blog
  filename: index.xml
  path: /feed/index.xml
  id: https://www.robin.is/
author:
  name: robindotis
  email: admin@robin.is
  url: https://www.robin.is/about/
  webmention: https://github.com/robindotis/

References

Below are some excellent links to further technical information and documentation on the technologies used for this site generator.

• Writing the content with Markdown and HTML.
• Styling the site with (CSS).
• Scripting functionality with (JavaScript).
• Modifying the sites structure using the Twig template language.
• For the really adventurous: adapting the site generation engine using PHP.
• Webhooks eg for EU hosting
• GitHub Pages
• RSS, sitemap, SEO etc