Eleventy Markdown Prime

Sample 2023 pinned event

example@example.com (Dmitry Golubev) — Fri, 09 Jun 2023 00:00:00 +0000

What a great event

This sample displays badges, attendance and a disabled event button from Markdown front matter. The values and event status are authored manually; there is no registration workflow or live counter.

Getting Started

example@example.com (Dmitry Golubev) — Fri, 23 May 2025 00:00:00 +0000

This guide covers creating an Eleventy Markdown Prime (EMP) repository, configuring the site, adding content and deploying it.

Create Your Site Repository
Run the Template Locally (Optional)
Site Structure
File Structure
Configuration Files
Posts and Pages
Deploying to Cloudflare Pages
Other Deployment Environments

Create Your Site Repository

To build your website, you need your own copy of the EMP starter repository. This allows you to customize the site, save your changes, and deploy it online. The EMP starter repository is available here: EMP Starter Repository.

Steps to Create Your Repository

Go to the EMP Starter Repository.
Click Use this template or Fork (see the next section for guidance on which to choose).
Name your repository and choose public or private.
If you want to edit files locally on your computer, clone your repository:
Code
```
git clone 
cd 
```
Alternatively, you can edit files directly in your repository using GitHub’s web interface. Simply navigate to the file you want to edit, click the pencil icon, make your changes, and commit them.

Fork vs Template: Which Should You Choose?

Use this template: Creates a new repository in your GitHub account with no connection to the original. Best if you want a clean start and don’t plan to sync updates from the EMP repository.
Fork: Creates a copy of the repository in your GitHub account, keeping the full history and a link to the original (upstream). Ideal if you want to pull future updates from EMP or contribute back.

Note: Changes to layouts, configuration or build scripts may need manual adaptation when merging upstream updates, especially if your directory structure differs from EMP.

Keeping Your Repository Updated

If you forked:
1. Open your fork on GitHub.
2. Click Sync fork (or Fetch upstream) to pull updates from the EMP repository.
3. Alternatively, use the command line after adding the original repository as an upstream remote (once per clone):
  Code
```
git remote add upstream https://github.com/lastguru-net/emp.git
```
  Then fetch and merge updates:
  Code
```
git fetch upstream
git merge upstream/main   # or: git rebase upstream/main
git push
```
If you used the template:
Your repository has no shared commit history with EMP, so GitHub’s Sync fork option is not available. If you need updates, you can manually copy changes from the EMP repository.

Run the Template Locally (Optional)

Running the site locally is optional. If you prefer, you can skip this step and deploy your site directly from the repository. See the Deploying to Cloudflare Pages section for details.

If you want to preview and edit your site locally, follow these steps.

Prerequisites

Install Git: Download Git.
Install Node.js 24 or newer and npm:
- Visit the Node.js Download Page, which provides both prebuilt packages and instructions for setting up a version manager (e.g., nvm).
- Using a version manager is recommended as it makes it easier to update Node.js in the future.
Verify installation:
Code
```
node -v
npm -v
```

Running the Site Locally

Go to the repository folder.
Install dependencies:
Code
```
npm install
```
Start the development server:
Code
```
npm run dev
```
Open the URL shown in the terminal (usually http://localhost:8080) to preview your site.

For more detailed guides on setting up Node.js and npm, check:

Site Structure

The regular layout has four areas:

Sidebar: Always visible on larger screens and hidden on mobile devices. The sidebar is defined in the configuration files and includes:
- Site logo or profile image
- Site title and description
- Main menu (manually defined for full control)
- Search button (opens a search modal window)
- Social links (GitHub, LinkedIn, Mastodon, etc.), shown in the sidebar or footer
Top Bar: Displayed only on mobile devices. It shows the site title and provides a hamburger icon to show the sidebar.
Content Area: Always visible on all screens, this is where your site content is displayed. Depending on the location, it serves the following purposes:
- Index Page (Landing Page): The first page visitors usually see.
  - Features an optional header image on top.
  - Lists non-hidden posts newest first, with pinned posts at the top. Each post includes a title, description (or excerpt), and optional properties like date, location, author, tags, and reading time.
  - Optional thumbnails can be enabled and placed on the left or right; they are responsive and clickable.
  - If there are more than a configured number of posts (10 by default), pagination with navigation controls appears at the bottom.
- Tag Page: Similar to the landing page but without a header image. Lists posts with a specific tag (e.g., “events”).
  - Supports pagination and is generated automatically for each tag.
- Author Page: Similar to the landing page but without a header image. Lists posts by a specific author (e.g., “lastguru”).
  - Supports pagination and is generated automatically for each author.
  - When enabled, an author business card (photo, bio, website/email, socials) is displayed above the list.
- Post: The most common content type - a blog post.
  - Includes a title, date, and optional image. Additional properties like location, author, and tags can be added.
  - Below each post, share buttons and navigation buttons for newer/older posts are available.
- Page: Special content like “About Us.” Pages are not listed among blog posts and do not include dates, post properties, or navigation buttons. They are typically linked directly in the main menu or from other posts or pages.
Footer: Optional footer with social links, copyright information, privacy policy link and “Powered by” link.

File Structure

Site content, configuration and templates are stored in these files and directories:

Utility configuration files are located in the root folder (e.g., /package.json, /eleventy.config.mjs). Avoid modifying these unless necessary.
/_11ty: Contains custom components that enhance Eleventy. Scripts for tasks like image transformation, link transformation, and excerpt generation are located here. Modifications are rarely needed.
/assets: Stores shared files for your site. You can modify or add files here. Visitors can access these files via direct links.
- css: Contains CSS source files. Eleventy assembles them through content/utils/css.njk, and Tailwind CSS compiles and minifies the result into _site/assets/css/min.css. Add custom styles in custom.css.
- js: Contains JavaScript files. The min.js file is generated by Eleventy (content/utils/js.njk) by inlining feature scripts.
/content: Contains all site content.
- _data: Stores site configuration (see below).
- _includes: Contains template files for HTML output.
- images: Stores image files. Images displayed in page content are automatically optimized and converted to various formats and sizes. Special images like the favicon are also stored here.
- pages: Contains page files.
  - pages.json: Defines default variables for pages.
- posts: Contains post files. For better organization, posts are subdivided into year-based subfolders (e.g., /2025/). Subfolder names do not appear in URLs, so you can name them freely. For smaller sites, this organization is optional.
  - posts.json: Defines default variables for posts.
- utils: Contains additional templates like the “Error 404” page and robots.txt.
- index.njk: Template for the landing page.
- index.11tydata.js: Pagination size control for the landing page.
- author.njk: Template for author pages.
- tag.njk: Template for tag pages.

Configuration Files

Edit the following files to configure the site:

`/content/_data/siteconfig.js`

This file contains the essential configuration settings for your site. It defines global properties such as the site title, URL and main images. There are comments for every setting in the file itself. Key sections include:

Site Metadata: Title, description, author, and locale settings.
Images: Paths for the sidebar profile image, favicon, and OpenGraph default image.
Integrations: Optional Google tag and Meta app/pixel configuration.
Pagination: number of posts per page, and the link prefixes for author/tag pages.

This file is the starting point for setting up your site.

`/content/_data/siteelements.json5`

This file contains configuration for site-specific elements such as menu items, fonts, social media links, header and footer settings. Key sections include:

Features: Settings for post properties, JSON-LD structured data, sitemap and feed links, and social sharing buttons. The sitemap and feed files are generated regardless of their link settings. Set features.postproperties to "below" (default) or "above" for placement relative to the full-post image, or false to hide properties everywhere. true also places properties below the image.
Fonts: Google Fonts configuration for body and header typography that can be later used in theme.css.
Menu: Labels and URLs for the home link and additional menu items.
Header: Header image for the landing page.
Social Links: Links to social media profiles (e.g., GitHub, LinkedIn, Mastodon). Also used for share attribution (e.g., X “via”).
Privacy Policy: Configuration for the privacy policy link.
Powered by: Powered by text and link.
Copyright: Settings for copyright year, link, and text.

Modify this file to customize visible elements, navigation and site identity.

JSON postlists

Set features.index: "json" and features.js: true to load post lists from JSON in the browser. This applies to the homepage and tag and author archives. Use features.index: "postlist" (the default) to render post lists during the build.

The build exports Markdown posts to JSON files in a postlist/ directory beneath each list’s first page. For example, /postlist/1.json contains the first page of the homepage list, and /events/postlist/2.json contains the second page of the events list. Your static host serves these files.

To load JSON from another source, set postlist.source in the page’s front matter or Eleventy data:

YAML

postlist:
  source: /data/events/

With this setting, EMP requests /data/events/1.json, /data/events/2.json, and so on. You supply those files or responses; EMP does not export Markdown posts for that list.

Use a path from the site root or an absolute HTTP(S) URL. EMP adds the deployment prefix to site-root paths: with a /blog/ deployment, /data/events/ becomes /blog/data/events/. Do not put that prefix in postlist.source. A trailing slash is optional. A source on another origin must allow cross-origin requests (CORS); requests omit credentials.

For a custom list, use layout: base.njk and include postlist.njk in a Nunjucks page. Set its postlist.source and enable JSON mode as above. The source can provide posts without corresponding local Markdown files. Pages whose permalinks do not end in / require an explicit source directory.

Each JSON response contains the cards for one page and pagination metadata:

JSON

{
  "items": [{ "url": "/workshop/", "title": "Workshop", "excerpt": "A practical introduction." }],
  "pagination": { "page": 1, "totalPages": 8 }
}

page is a one-based page number and totalPages is the number of pages in the list. For an empty list, 1.json returns items: [] and pagination: { "page": null, "totalPages": 0 }.

Each item requires a url and a title. Optional fields are excerpt, pinned, thumbnail and properties. Supply text without HTML or HTML escaping. For links and images, use site-root paths that include the deployment prefix, or absolute URLs. Site-root paths refer to the website, not the JSON host.

A thumbnail contains src and optional srcset, sizes, width and height. Its optional sources array contains objects with type and srcset for alternative image formats. The optional numeric lqip field supplies the blur placeholder.

The properties object accepts:

date: formatted date text.
author: an object with name and url.
place: an object with name and optional address.
tags: an array of objects with name, url and optional icon.
readingTime: an object with label and wordsLabel.
decorations: the post decoration fields.

Icon names refer to entries in inlinesvg.json5. Markdown exports supply formatted text, image variants and links; use an exported JSON file as a reference when creating your own source.

Pagination links use ?page=N; JSON requests use N.json. Reload, new tabs and browser Back/Forward select the page in the URL. Without a valid page query, an HTML page loads its corresponding JSON page. Use one list per HTML page.

If a request fails, the displayed cards and pagination links stay available. Click the link again to repeat the request, or reload if the initial load failed. Configure empty-list and error messages in sitestrings.json5.

`/content/_data/sitestrings.json5`

This file defines text strings used throughout the site. It allows you to customize or translate common UI elements such as:

Labels: Words like “Share,” “Older,” “Newer,” and “Events.”
Tooltips: Text for actions like “Copy page link to clipboard” and “Copied.”

You can add your own keys and reference them in templates. Use it to adapt the site’s language and tone. Note that multiple languages can be defined there. The language is selected by the lang option in the siteconfig.js.

`/content/_data/sitetags.json5`

This file manages tag-related configurations for posts. It includes:

notime: Tags that hide post reading time in post properties (e.g., “events”).
notag: Tags that are hidden in post properties (e.g., “article,” “posts”).
events: Tags that trigger Event JSON-LD instead of BlogPosting.
icons: Overrides for the standard tag icon in post properties.
aliases: Overrides the link to the tag page.

This file helps control how tags are presented and used across the site.

`/content/_data/siteauthors.json5`

This file defines per-author metadata used to render the author business card on author pages. Each top-level key is the author identifier used in your post header variables (author: "name"). If an author has no entry here, the business card is not displayed. The card can show the author’s name, profile image, bio, and links to a website and social media.

`/assets/css/theme.css`

This file defines the core theme styles for your site, including fonts, colors, and layout spacing. It uses CSS custom properties (variables) to ensure flexibility and consistency across the site. Key sections include:

Fonts: Defines the primary fonts for the body and headers using the --font-body and --font-header variables.
Colors: Defines the palette for backgrounds, text, and common UI states, plus the accent color (--color-accent) used on interactive highlights and hovers.
Spacing: Configures the maximum width for content (--spacing-content) and the width of the sidebar (--spacing-sidebar).

Notes:

Use fonts installed on visitors’ devices or load web fonts. EMP supports Google Fonts through /content/_data/siteelements.json5; use the corresponding font family names in theme.css. The fallback fonts in each list are used when the preferred font is unavailable.
The content area uses --color-rightarea-bg and --color-rightarea-bg-dark for its light and dark backgrounds. The mobile top bar uses --color-topbar-bg and --color-topbar-bg-dark, which default to the light content background and sidebar background respectively.
The footer background (--color-footer-bg) defaults to the sidebar background (--color-sidebar-bg).

This file is processed by Tailwind CSS to generate the final min.css file, which is used to style the site. You can extend or override these variables to customize the theme further.

Posts and Pages

Posts and pages are written in Markdown, a simple and widely-used markup language. You can learn more about Markdown’s features on the Text and Typography page. Each Markdown file has a .md extension and consists of two parts: a header and a content body.

Example:

Markdown

---
title: "Sample 2023 Event"
date: "2023-06-09"
place: "Somewhere over the rainbow"
tags: events
excerpt: "Excerpt of the description for the sample event."
---

## What a Great Event

Sample event. Please visit us.

Editing with PagesCMS (Optional)

If you prefer a more user-friendly editing experience (especially for non-technical editors), you can manage your EMP content with PagesCMS. PagesCMS connects to your GitHub repository and provides a browser-based editor for Markdown content. Changes are saved back to the repository as commits, which then trigger your normal deployment pipeline (e.g., Cloudflare Pages rebuilds automatically).

Header Variables

The header contains metadata for the post or page. Set title for both posts and pages, and an explicit date for posts. Supported variables include:

title (required): The title of the post or page. The URL is based on the title unless overridden in the header.
date (recommended for posts): The publication date in YYYY-MM-DD format or with time in YYYY-MM-DD HH:MM:SS or YYYY-MM-DD HH:MM:SS +/-TTTT format.
updated: Optional last modification date in the same formats as date. When present, it is used in JSON-LD, the sitemap, and the Atom and JSON feeds.
permalink: Overrides the default URL for the post/page.
image: Path to the title image, relative to the content folder.
thumbnail: Optional path for a thumbnail image to use in post lists instead of the title image. To hide the thumbnail completely instead, use thumbnail: false.
excerpt: A description used in post lists. If defined, it has no length limit. If omitted, an excerpt is generated from the first nonempty line of rendered content after removing HTML tags, shortened to at most 250 characters at a word boundary where possible. An ellipsis is added when content is omitted.
tags: One or more tags for the post. Depending on the configuration, some (or all) of the tags are displayed in the post lists.
author: The author identifier, matching a key in siteauthors.json5 when author metadata is provided. Used to generate author pages; the author’s fullName is displayed when configured, otherwise the identifier is shown.
place: The location of the post. Displayed in post lists, commonly used for events.
address: The location address of the event. Displayed as a tooltip for place and in the Event JSON-LD structured data.
profilePage: When set to true on a page (not a post), generates ProfilePage JSON-LD and a corresponding Person/Organization node describing the site publisher. Commonly used for pages like “About Us.”
hidden: When set to true on a post or page, excludes it from listings, search, the sitemap and feeds. Its HTML file is still generated and accessible by URL, so this does not make a draft private.
pinned: When set to true, puts the post ahead of unpinned posts in landing and author/tag listings, the sitemap and feeds. Within each group, posts are sorted newest first.

The posts.json and pages.json files contain the default header variables. The most important setting there is permalink, which defines how URLs are generated for pages and posts. You can customize the default URL there. Note that the system depends on the layout and tags variables as they are set there, so it is not recommended to change them.

Post decorations

Posts can add optional decorations to their front matter. They appear with post properties in lists and on full posts; siteelements.features.postproperties controls both.

YAML

decorations:
  badges:
    - label: "Workshop"
      variant: primary
  metrics:
    - label: "Participants"
      value: 18
      max: 30
      progress: true
    - label: "Capacity"
      max: 30
  actions:
    - label: "Sign up"
      href: "https://example.org/register"
      icon: calendar
      variant: primary

Badges require a label. Badges and actions share the optional variant: neutral (default), primary (site accent), success or warning.
Metrics take a label and a numeric value, max, or both. Zero is displayed; a maximum alone does not imply a current count. Optional progress: true adds a bar when a value and positive maximum exist. The text retains the actual numbers even beyond the maximum.
Actions require a label. A supplied href produces a normal link; without it, the control is a button with no attached behavior. Optional icon names an entry in inlinesvg.json5; omit it for text-only controls.
disabled: true produces a disabled, non-navigating button, even if href is present. For a closed event, you can use label: "Closed", variant: warning and disabled: true. The sample event demonstrates a neutral “Past event” button with an icon. A text-only signup link simply omits icon.

Each decoration group is optional. Set labels, numbers and availability in front matter; they do not update automatically from the event date or capacity. Point signup links to your registration service.

Deploying to Cloudflare Pages

Cloudflare Pages builds the site from your Git repository and serves the generated files over HTTPS. Pushes to the configured production branch trigger a build and deployment.

Steps to Deploy

Ensure you have a Cloudflare account. If not, create one at Cloudflare. It is free.
Push your project to a Git repository (GitHub or GitLab).
Create a new project:
- Log in to your Cloudflare account and navigate to the Workers and Pages section.
- Click Create, select Pages, and connect your Git repository.
Configure build settings:
- In the Build settings section, set:
  - Framework preset: Eleventy
  - Build command: npm run build
  - Output directory: _site
- Add an environment variable:
  - NODE_ENV: production (enables HTML, feed and JavaScript minification)
Start Deployment:
- Click Save and Deploy. Cloudflare Pages will build and deploy your site.
- Once the deployment is complete, you will receive a unique URL for your site.

Custom Domain (Optional)

To use a custom domain:

Open your Cloudflare Pages project you just created.
Go to the Custom domains section.
Add your domain and follow the instructions to configure DNS settings.

Other Deployment Environments

EMP can also be deployed on Netlify, Vercel, GitHub Pages or another static host. Build with NODE_ENV=production and publish the contents of _site. Configure the host’s build workflow according to its documentation.

Text and Typography

example@example.com (Dmitry Golubev) — Sat, 19 Apr 2025 00:00:00 +0000

Headings

H1 - heading

H2 - heading

H3 - heading

H4 - heading

Paragraph

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Emphasis

Italic text

Bold text

Bold italic text

Strikethrough ~~text~~

Highlighted text

Subscript: H₂O

Superscript: X²

Inline code: So much code.

Links

Just link: http://127.0.0.1

Just email: fake@example.com

Text link: Dmitrijs Golubevs

Special symbols

Plenty of emojis are available, like: ⚠️ 💡 📡 😄 ⛺ 😂 💗

Lists

Ordered list

Firstly
Secondly
Thirdly

Unordered list

Chapter
- Section 1
- Section 2

ToDo list

Job
- Step 1
- Step 2
- Step 3

Description list

Sun: the star around which the Earth orbits
Moon: the natural satellite of the Earth, visible by reflected light from the Sun

Block Quote

This line shows the block quote. The quote may contain multiple lines or even paragraphs

Admonitions

⚠️ Warning: Do not push the big red button.

📝 Note: Sunrises are beautiful.

💡 Tip: Remember to appreciate the little things in life.

Tables

Company	Contact	Country
Alfreds Futterkiste	Maria Anders	Germany
Island Trading	Helen Bennett	UK
Magazzini Alimentari Riuniti	Giovanni Rovelli	Italy

Table 1: a sample table. Note that you can align text in the columns to the left, right or center.

Footnote

Clicking the hook will locate the footnote^[1], and here is another footnote^[2].

Code blocks

Every fenced code block includes a one-line header based on its language. Add filename="..." or title="..." after the language identifier to show more context alongside the language. If both fields are supplied, title takes precedence over filename. Long titles preserve their beginning and use a trailing ellipsis; long filenames preserve their end and use a leading ellipsis.

Common

Text

This is a common code snippet, without syntax highlight and line numbers.

Specific Language

status-check.shBash

if [ $? -ne 0 ]; then
  echo "The command was not successful.";
  #do the needful / exit
fi;

Raw HTML

Raw HTML can be written directly in Markdown. This example first shows the source in a code block with a custom title:

Expandable raw HTMLHTML

<details>
  <summary>Show raw HTML content</summary>
  <p>This content is rendered directly from HTML.</p>
</details>

The same markup rendered as raw HTML:

Show raw HTML content

This content is rendered directly from HTML.

Images

Default

Image 1: Sample image

Linking images

Image 2: Sample image with a link

Embeds

The following services can be embedded:

Instagram
OpenStreetMap
Spotify
TED
TikTok
Twitch
Twitter
Vimeo
YouTube

Example:

https://www.youtube.com/watch?v=dQw4w9WgXcQ

Reverse Footnote

The footnote source ↩︎
The 2nd footnote source ↩︎

Sample article

example@example.com (Dmitry Golubev) — Sun, 19 Feb 2023 00:00:00 +0000

This is a very interesting article. It deserves to be read! The excerpt is generated automatically from the first line, and is shortened to at most 250 characters before an ellipsis, preserving whole words where possible (but the excerpt can be specified manually, in which case it does not have a length limit). Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Eleventy Markdown Prime

Sample 2023 pinned event

What a great event

Getting Started

Table of Contents

Create Your Site Repository

Steps to Create Your Repository

Fork vs Template: Which Should You Choose?

Keeping Your Repository Updated

Run the Template Locally (Optional)

Prerequisites

Running the Site Locally

Site Structure

File Structure

Configuration Files

/content/_data/siteconfig.js

/content/_data/siteelements.json5

JSON postlists

/content/_data/sitestrings.json5

/content/_data/sitetags.json5

/content/_data/siteauthors.json5

/assets/css/theme.css

Posts and Pages

Editing with PagesCMS (Optional)

Header Variables

Post decorations

Deploying to Cloudflare Pages

Steps to Deploy

Custom Domain (Optional)

Other Deployment Environments

Text and Typography

Headings

H1 - heading

H2 - heading

H3 - heading

H4 - heading

Paragraph

Emphasis

Links

Special symbols

Lists

Ordered list

Unordered list

ToDo list

Description list

Block Quote

Admonitions

Tables

Footnote

Code blocks

Common

Specific Language

Raw HTML

Images

Default

Linking images

Embeds

Reverse Footnote

Sample article

`/content/_data/siteconfig.js`

`/content/_data/siteelements.json5`

`/content/_data/sitestrings.json5`

`/content/_data/sitetags.json5`

`/content/_data/siteauthors.json5`

`/assets/css/theme.css`