kbenestad/mdcms
1
0
Fork 0
mirror of https://github.com/kbenestad/mdcms.git synced 2026-06-18 15:24:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
mdcms/docs/reference-config.md

7.7 KiB
Raw Blame History

config.yml reference

config.yml is the site configuration file. Only sitename and navigation are required — everything else is optional. mdcms build reads this file; so does index.html at runtime.

The first line must not be changed:

# mdcms v0.4 | DO NOT REMOVE THIS COMMENT

Required

sitename: My Site              # Displayed in the browser tab, nav header, and meta tags.
navigation: sidebar            # Layout mode. sidebar or topbar. NOTE: topbar is currently broken — always use sidebar.

Presentation

theme: theme.yml               # Path to theme file (relative to site root). Controls colours, fonts, layout.
                               # Omit to use built-in defaults.

logo: logo.png                 # Filename in assets/images/. Shown in the nav header above the site name.
favicon: favicon.png           # Filename in assets/images/. Shown in the browser tab.
                               # Falls back to logo if not set. Required for PWA install icons.

sitedescription: A short description   # Shown below the site name in the sidebar.
                                       # Also used as the default meta description tag.

footer: "© 2026 Your Name"     # Shown at the bottom of the nav. Supports inline markdown (bold, links, etc.).

Navigation

homepage: pages/home.md        # Override the default landing page. Path relative to site root.
                               # Default: pages/home.md

nav-position: left             # Sidebar position. left or right. Default: left.
                               # Only applies when navigation: sidebar.

search: true                   # Show the search box. Set to false to hide it.
                               # Default: true (search is on unless explicitly disabled).

Theme mode

default-theme: system          # Starting colour mode. light, dark, or system.
                               # system follows the user's OS preference.
                               # Default: system.

Layout overrides

These can also be set in theme.yml. Values here apply on top of theme.yml.

main-width: 80em               # Maximum width of the content column. Any CSS length unit.
nav-width: 20em                # Width of the sidebar. Any CSS length unit.

Typography overrides

These can also be set in theme.yml. Values here apply on top of theme.yml.

font-body: "bunny:Noto Sans:400"      # Body font. Format: "provider:Font Name:weight"
font-title: "bunny:Noto Sans:700"     # Heading font.
font-code: "bunny:Fira Code:400"      # Code font.

Provider options: bunny (GDPR-safe) or google. Omitting the provider defaults to Bunny Fonts.

Localisation

language: en                   # BCP 47 language code. Used for date formatting fallback.

date: system                   # Date format for post dates. system uses the browser locale.
                               # Or provide a format string, e.g. DD.MM.YYYY

time: system                   # Time format. system uses the browser locale.

monthnames: January, February, March, April, May, June, July, August, September, October, November, December
                               # Override month names (comma-separated, 12 values).

monthnamesabbreviated: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
                               # Override abbreviated month names (comma-separated, 12 values).

pagenotfoundmessage: "Page not found."   # Message shown when a page cannot be loaded.

PWA (Progressive Web App)

mdcms build generates manifest.json and service-worker.js when pwa: yes.

pwa: yes                       # Enable PWA. Generates manifest.json and service-worker.js on build.

pwa-name: "My Site"            # Full app name shown on the install prompt and splash screen.
                               # Required when pwa: yes.

pwa-shortname: "MySite"        # Short name for home screen icon labels (keep under ~12 chars).
                               # Falls back to pwa-name if omitted.

pwa-colour: "#2563EB"          # Browser chrome colour (address bar on Android Chrome).

offline-message: "You are offline. Connect and reload."
                               # Shown when a page cannot be fetched and no cached version exists.
                               # Supports per-language values (see below).

Multi-language offline message:

offline-message:
  en: "You are offline. Connect and reload."
  nb: "Du er frakoblet. Koble til og last inn på nytt."

The renderer picks the entry matching the active category's language, then falls back to en, then the first entry.

Requires a favicon.png (192×192 px recommended) at assets/images/favicon.png for the PWA install icon.

Categories

Categories allow one site to serve multiple language or audience variants of the same content. Each page can have a variant per category using the filename suffix convention (page.nb.md for Norwegian).

categories-use: yes            # Enable the category system. Default: no.

default-category:              # The category used when no ?cat= parameter is in the URL.
  code: en                     # Short code. Used in filenames (page.en.md) and URL params.
  name: English                # Display name shown in the category selector.
  direction: ltr               # Text direction. ltr or rtl. Default: ltr.

categories:                    # Additional categories.
  - code: nb
    name: Norsk
    direction: ltr
  - code: ar
    name: عربي
    direction: rtl             # RTL flips nav position and content text direction.

categories-sectionnames: same  # How section names are shown per category.
                               # same: all categories share one section name (defaultname in nav.yml).
                               # per-category: each section has a name per category (categorynames in nav.yml).

categories-selecticon: globe   # Icon shown in the category selector bar. SVG name from assets/icons/.
categories-selecttext: "Language"  # Label shown next to the icon in the category selector bar.

Reusable callout messages

Define named messages in config.yml and reference them in markdown with message: <key>. Useful for standard notices (e.g. AI translation warnings) used across many pages.

callouts:
  aitranslation:               # Key name — used as message: aitranslation in markdown.
    type: warning              # Callout type: info, warning, success, error.
    en:
      title: "PLEASE NOTE:"
      text: This page has been translated with artificial intelligence.
    nb:
      title: "VENNLIGST MERK:"
      text: Denne siden er maskinoversatt.

Usage in a markdown page:

```mdcms
callout-warning
message: aitranslation
```

Full example

# mdcms v0.4 | DO NOT REMOVE THIS COMMENT
# MD-CMS v0.4 — Site configuration

sitename: My Documentation
navigation: sidebar
theme: theme.yml

logo: logo.png
favicon: favicon.png
sitedescription: Reference documentation for My Project
footer: "© 2026 My Name — [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)"

homepage: pages/home.md
nav-position: left
search: true
default-theme: system

pwa: yes
pwa-name: "My Documentation"
pwa-shortname: "MyDocs"
pwa-colour: "#2563EB"
offline-message:
  en: "You are offline. Connect to the internet and reload."
  nb: "Du er frakoblet. Koble til og last inn på nytt."

language: en

callouts:
  aitranslation:
    type: warning
    en:
      title: "PLEASE NOTE:"
      text: This page has been translated with artificial intelligence. It has not been reviewed by staff.
    nb:
      title: "VENNLIGST MERK:"
      text: Denne siden er maskinoversatt og ikke gjennomgått av redaksjonen.