Advanced Setup
These optional setups extend a working Eleventy Markdown Prime (EMP) site. For repository creation, basic configuration, content authoring and deployment, start with Getting Started.
Table of Contents
Sidebar user menu
Setfeatures.userMenu: truewithfeatures.js: trueto show a User button at the bottom of the regular sidebar. Its modal contains Sign in or Sign out and, whenfeatures.privacyPolicyis"sidebar", the configured policy link. The option is off by default. A method can setauthentication.errorto show the normal error status without discarding a restored identity.
Select the browser-only test method incontent/_data/siteconfig.js:
authentication: { method: "test", options: {} },The test method uses the existinglocalStorage.uservalue, restores stored names with the stable idtest-user, signs in asTest Username, and removes only that key on sign out. Setmethod: nullto disable authentication output; if the user menu is enabled at the same time, its sign-in control remains visible but inactive until a method is selected.
Method sources live in_11ty/authentication/and are registered in itsindex.js; only the selected source is bundled. Each defines anauthenticationobject with asynchronousrestore(),signIn()andsignOut()functions, returning{ id, name }ornull. The menu uses that result after every action. Public settings fromauthentication.optionsare available to the implementation asauthenticationOptions; the test method needs none.
JSON postlists
Setfeatures.index: "json"andfeatures.js: trueto load post lists from JSON in the browser. This applies to the homepage and tag and author archives. Usefeatures.index: "postlist"(the default) to render post lists during the build.
The build exports Markdown posts to JSON files in apostlist/directory beneath each list’s first page. For example,/postlist/1.jsoncontains the first page of the homepage list, and/events/postlist/2.jsoncontains the second page of the events list. Your static host serves these files.
For a custom list, uselayout: base.njk, a directory permalink such as/events/, and includepostlist.njkin a Nunjucks page with JSON mode enabled. Supply local items throughposts. An empty local list still generates/events/postlist/1.jsonand fetches its read URL, allowing that endpoint to supply posts.
Each JSON response contains the cards for one page and pagination metadata:
{
"items": [{ "url": "/workshop/", "title": "Workshop", "excerpt": "A practical introduction." }],
"pagination": { "page": 1, "totalPages": 8 }
}pageis a one-based page number andtotalPagesis the number of pages in the list. For an empty list,1.jsonreturnsitems: []andpagination: { "page": null, "totalPages": 0 }.
Each item requires aurland atitle. Optional fields areexcerpt,pinned,thumbnailandproperties. 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.
Athumbnailcontainssrcand optionalsrcset,sizes,widthandheight. Its optionalsourcesarray contains objects withtypeandsrcsetfor alternative image formats. The optional numericlqipfield supplies the blur placeholder.
Thepropertiesobject accepts:
date: formatted date text.author: an object withnameandurl.place: an object withnameand optionaladdress.tags: an array of objects withname,urland optionalicon.readingTime: an object withlabelandwordsLabel.decorations: the post decoration fields.
Icon names refer to entries ininlinesvg.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 useN.json. Reload, new tabs and browser Back/Forward select the page in the URL. Without a validpagequery, 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 insitestrings.json5.
JSON read sources
By default, JSON postlists and JSON metrics/actions read the files generated by EMP from your static host. Configure a read prefix when another path or service should supply those responses.
SetjsonReadPrefixincontent/_data/siteconfig.jsto change where browsers read postlist and metrics/actions JSON. The default""reads generated files at their normal URLs. With"/api", the homepage still generatespostlist/1.json, while the browser requests/api/postlist/1.json. Generated files and links inside responses keep their canonical paths.
The read prefix goes before the deployment-prefixed path: with/blog/, the request is/api/blog/postlist/1.json. A trailing slash is optional. An absolute HTTP(S) prefix such ashttps://data.example/apisupports another origin, which must allow cross-origin requests (CORS). The host at the read URL supplies the responses.
JSON metrics and actions
Setfeatures.liveMetricsActions: trueincontent/_data/siteelements.json5to load metrics/actions for full posts and static list cards. The defaultfalserenders their authored values directly. JSON lists render metrics/actions from each item in the list response, alongside the rest of the card data.
Eleventy generatesmetrics-actions.jsonbeneath each displayed post’s URL from the prepared front matter used for static rendering and JSON lists. For example,/sample-2023-pinned-event/and its static list cards load/sample-2023-pinned-event/metrics-actions.json. The JSON read source configured throughjsonReadPrefixapplies to these requests and explicit refreshes.
The sample event’s existing Markdown decorations produce metrics/actions in this format:
{
"metrics": [
{ "label": "Participants", "value": 24, "max": 30, "progress": true }
],
"actions": [
{ "label": "Past event", "icon": "calendar", "variant": "neutral", "disabled": true }
]
}When enabled, metrics/actions on full posts and static list cards start empty and load silently from the generated JSON. Posts without metrics or actions export empty arrays. Bothfeatures.jsandfeatures.postpropertiesmust be enabled. Without JavaScript, full posts and static lists keep their content and badges readable.
In JSON list mode, each list response supplies the cards’ metrics/actions, including on pagination. External list publishers supply these fields in each item’sproperties.decorations. Full posts continue to usemetrics-actions.json. The default page layout does not display post properties. Cross-origin requests require CORS. Action URLs in responses must include any deployment prefix.
Every response must contain bothmetricsandactionsarrays, with a stringlabelfor each item. The shared renderer handles the post decoration fields. Each array replaces its whole group;[]clears it. Numbers must be JSON numbers, not strings. Omit an unknownvalueor set it tonull; it is not zero. A failed request or invalid response structure leaves the last valid presentation intact, or the initial region empty.
For full posts and static list cards, EMP fetches once on initialization. Custom JavaScript can refresh a region through the same loader:
const region = document.querySelector("[data-metrics-actions-url]");
region?.dispatchEvent(new Event("metricsactions:refresh"));An update affects only that region; responses for removed regions or superseded refreshes are ignored. Action links navigate normally; action buttons require application-provided handlers.