Welcome to the mdlake guide

mdlake is a content system and a site builder that share one idea: you write each thing once, and everything else reads it from there.

The CMS is where editors write. It looks like a word processor, but what it saves is plain Markdown in a Git repository, one repository per client. We call that repository the lake. The builder is a Claude Code plugin that developers use to generate and grow websites and small web apps from a lake. A generated site does not copy text into code. It points at documents and images in the lake by ID, so editors keep control of the words after launch.

Who this guide is for

The guide has two main audiences, and a third group that sits in between.

• Editors write, organise and publish content in the CMS. You do not need to know anything about Git, Markdown or code. You need a browser and an invitation.
• Developers install the CMS, connect it to GitHub, build sites from a lake with Claude Code, add forms and backends, and deploy to Azure. The team works on Windows, so commands are shown for PowerShell wherever they differ from Bash.
• Admins are people with the Admin role in the CMS. They create workspaces, invite people, manage access tokens and watch AI costs. An admin is often also a developer, which is why the role is described in both parts of the guide.

Each page lists who it is for in its tags. Where a page is mainly for one group, it says so in the first paragraph.

How the guide is organised

Where to start

If you are an editor

1. Read What is mdlake? for the five ideas you need: workspace, document, media, draft and published.
2. Follow Writing documents to write your first page.
3. Read Publishing before you publish anything. Published content can end up on public websites.
4. Keep The media library at hand. Every image needs alt text before it can be used.

If you are a developer

1. Read What is mdlake? to see how the CMS, the lake, the builder and the sites fit together.
2. Run the CMS on your machine with Install the CMS. It comes with a demo workspace, so you have content to build against at once.
3. Set up Claude Code with Install the builder.
4. Continue with How sites work and Plan a site.
5. When the site needs a form or a server, read Choose a hosting model.
6. To go live, start at Deploy overview.

If you are an admin

1. Install and configure the CMS: Install the CMS.
2. Add people: Users and invites.
3. Create a workspace for each client: Create a workspace.
4. Connect it to GitHub: Connect GitHub.
5. Create access tokens for developers and tools: Workspace tokens.
6. Keep an eye on AI costs: AI suggestions.

Conventions in this guide

• Names of buttons and menu items are in bold, exactly as they appear on screen: Import Markdown.
• File names, commands, settings and values are in code font.
• A callout marked Warning points at something that can lose work or leak a secret. Read those.
• Command examples use PowerShell when Windows and Bash differ, and Bash otherwise.