Getting Started with Accent

This walkthrough takes you from a fresh checkout to your first published edit through the admin UI. The full reference docs live next to it; this page is the canonical 1.0 onboarding.

Install

Accent CMS ships as one binary per platform: every download contains the full feature set, and a license key decides which tier is unlocked at runtime. Building a site and running the development server are free and need no key.

On Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/AccentCMS/accent/main/install.sh | sh

On Windows (PowerShell):

irm https://raw.githubusercontent.com/AccentCMS/accent/main/install.ps1 | iex

Or download the archive for your platform manually from the latest release (accent-<version>-<target>.tar.gz, or .zip on Windows) and place the accent binary on your PATH.

Every release is checksummed and GPG-signed. The install script verifies both automatically; to verify a manual download, see Verifying downloads.

Instant preview

Already have a markdown file? You do not need a project at all – point serve straight at it:

accent serve README.md

The file renders at http://localhost:4400/ with a built-in viewer theme. No config.yaml, theme, or content directory has to exist on disk – nothing is written or extracted anywhere. The title comes from the file’s frontmatter title, falling back to the first # heading, then the filename. Images and other files sitting next to it resolve as you would expect, and editing the file refreshes the browser automatically.

Point it at a directory to browse a whole folder of notes with the same viewer theme:

accent serve ./notes/

Each markdown file becomes a page; a default.md, README.md, or index.md in the directory root is the home page. To preview a folder with your own theme instead of the built-in viewer, add --theme-dir ./themes --theme my-theme.

Preview a remote markdown file

The markdown does not even have to be on your machine. Point serve at an http(s) URL and it fetches the document once and renders it the same way:

accent serve https://raw.githubusercontent.com/rust-lang/book/main/README.md

Use the raw file URL (the one that returns plain markdown), not the rendered web page – a code host’s HTML page is rejected with a hint to switch to the raw URL. Because the document is third-party content, two safety rules apply automatically: inline raw HTML is shown as text rather than executed, and relative links and images are rewritten to load from the source origin. The fetch is hardened with a request timeout, a 10 MB size limit, and a redirect cap, and never sends credentials.

By default the document is fetched once at startup. To keep a long-lived preview in sync with a changing source, add --refresh with a polling interval in seconds:

accent serve https://example.com/docs/runbook.md --refresh 60

Each poll only re-downloads when the origin reports a change; when it does, the page cache is refreshed and the browser reloads. A failed poll keeps the last good copy. --refresh is valid only with a URL target.

When you are ready to turn a preview into a real project, accent init scaffolds one.

Initialise a site

accent init my-site
cd my-site

init lays out the starter template: a config.yaml, a content/ directory with a homepage, and the default theme under themes/.

Start the dev server

accent serve

Visit http://localhost:4400. The home page is live. Editing any markdown file under content/ triggers a browser refresh in under a second.

Editing your first page in the admin Core+

The admin UI runs alongside the public site at /_admin/. Three gates must be true for the shell to mount: the binary must be built with the admin cargo feature (the default for Standard and Pro editions), a Core+, Standard, or Pro license must be loaded (the admin is a licensed feature in dev and production alike – a Core+ key is the cheapest tier that unlocks it), and admin.enabled in config.yaml must be true.

  1. Enable the admin and set a token. Add an admin section to config.yaml:

    admin:
  enabled: true
  token: "your-secret-admin-token-min-32-bytes"

    The token can also be supplied through the ACCENT_ADMIN_TOKEN environment variable, which takes precedence over the value in config.yaml. In production, use at least 32 bytes of entropy; a startup warning is logged for tokens shorter than 16 characters.

  2. Start the server:

    accent serve

  3. Open http://localhost:4400/_admin/login and enter your token. It is compared in constant time against the configured token; on success you land on the dashboard. Failed attempts re-render the form with an inline error; only failed attempts count toward the rate limit of 10 per minute, so a burst of legitimate logins never locks you out.

  4. Browse the dashboard. It lists the five most recently modified pages and a validation summary bucketed by severity, so you can see at a glance what changed and whether anything needs attention.

  5. Open a page from the pages list. Click Pages to reach /_admin/pages – a paginated, filterable list of every page – and open the page you want to edit. The editor opens in edit mode with one input per frontmatter field.

  6. Edit a field and watch the live preview. As you change a field, the editor re-renders a live preview from your current form values, giving immediate visual feedback before you commit the change.

  7. Save the page. The save path validates your input, checks for concurrent edits, writes the file, and appends an entry to the admin audit log. The cache layer invalidates automatically, so the public site reflects your change on the next request.

  8. Move the page through the workflow. The editor shows only the transitions legal from the page’s current state, so the available buttons depend on where the page is. New pages start as Published, so to send one into the editorial flow you choose Unpublish (back to Draft) or Archive. From Draft the flow runs Submit for review to Review, then Approve to Published. Published pages are publicly visible (subject to any date constraints); drafts and pages in review stay hidden from the public site.

Shareable by default

Every page the default theme renders ships complete Open Graph and Twitter Card tags, a build-safe canonical link, and a page-specific description, so links unfurl as rich cards on Slack, LinkedIn, X, Mastodon, and friends with no extra work. To make those cards as good as possible, set a few site-wide values in config.yaml:

site:
  name: My Site
  url: https://example.com        # required for absolute canonical / og:url
  description: A short site-wide description used when a page has none.
  meta:
    twitter:site: "@mysite"        # any platform tag is just a key

structured_data:
  default_image: /assets/social-card.png   # branded fallback card image

Per page, set description:, image:, or a meta: block in frontmatter to override the defaults. See Social Sharing and SEO Metadata for the full system.

What’s next