Writing documents

A document is one piece of knowledge: a service, a person, an FAQ answer. You write it in the editor, which looks like a word processor. The CMS saves it as plain Markdown. This page shows you how to create a document, what each part is for, and what happens while you type.

Before you start

• You can sign in and you are a member of the workspace (Users and invites).
• You know the difference between a draft and a published document (What is mdlake?). Everything you write here is a draft until you publish it.

The editor window

Open a workspace. The window has three columns:

The top bar has the workspace name, and the views Documents, Media and People.

On the home page, Continue where you left off lists the documents you edited last, Unpublished changes lists what is waiting to be published, and Needs attention points at problems such as images without alt text. Three cards sit at the top: New document, Import Word, PowerPoint or PDF and Upload files. A workspace with nothing in it also shows a box called Start your lake.

Create a document

1. Choose New, then Document. Or choose the New document card on the home page. Or open the menu of a folder and choose New document here.
2. The document opens at once in the folder you are working in, called Untitled, with the title selected.
3. Type the title.

Expected result: the status line above the page says Saving…, then Saved, and the document appears in the tree under its title.

A new document is created in the folder that is highlighted in the tree, or in the folder of the document you have open. If nothing is selected, it goes to the top level. You can move it later (Folders and tags).

The parts of a document

Title

The title is required and can be up to 200 characters. It is shown in the tree, in search results and in link text. If you leave a document as Untitled, a Suggest button above the title field can propose one (AI suggestions).

Summary

The summary is one or two plain sentences that tell a reader what they will find. It appears in search results, link previews and lists on sites. It is one paragraph: the Enter key does nothing in this field, and pasted line breaks become spaces.

The counter under the field shows 0 / 160. Up to 160 characters is the target. Between 161 and 300 characters it turns amber and says “May be cut off in search results”. More than 300 characters is refused: “At most 300 characters”.

A document without a summary is listed under Needs attention on the home page, so write one.

Tags

Tags are short words that group documents, such as services or fleet. Type a tag and press Enter or comma. Backspace in the empty field removes the last tag. You can paste a, b, c to add three at once.

• A tag can be up to 50 characters. A document can have up to 20 tags.
• Tags cannot contain quotes, square brackets, pipes or backslashes.
• Tags match without regard to case. If the workspace already uses Fleet, and you type fleet, the CMS uses the existing spelling.
• While you type, a list shows the workspace’s tags with how many documents have each, for example fleet · 12, and the choice Create "fleetx" for a new one.

More on tags in Folders and tags.

Body

The body is the text. Click the box marked Body, below its toolbar, and write. An empty document says Start writing… there. You do not need to know Markdown. The toolbar above the text has:

The lake supports a small, stable subset of Markdown, so that every site can show it:

• Headings from level 2 to level 4. The page title is the document title, so there is no level 1.
• Paragraphs, bold and italic text, quotes, bulleted and numbered lists, tables and horizontal rules.
• Links and images.
• Inline code. The editor keeps it when a document already has it, but the toolbar has no button for it.
• Code blocks.

The editor does not support underline, strikethrough, subscript, superscript, highlight or inline styles such as colours. The toolbar does not offer them. If you try anyway, the editor removes them again: the keyboard shortcut Ctrl+U, pasted text that carries such formatting, Markdown shortcuts and the Source view cannot add them. A document that already holds <u>, <sub> or <sup> tags (for example from an import) is opened without the tags, and the tags are also removed when the document is saved. The text between the tags stays. Code blocks and inline code are left as written.

You can also type Markdown shortcuts, such as ## at the start of a line for a heading, - for a bullet or > for a quote.

Code blocks

Choose Insert code block in the toolbar, or type three backticks and a space at the start of a line. Click in the block and type or paste the code.

The list at the top right of the block sets the language, which the site uses to colour the code and to label the block. Choose Plain text for anything that is not code. A language you type after the backticks is not kept, so choose it from the list. The bin next to the list removes the block.

• Moving in and out: the arrow keys move between the text and the code like between any two lines. Backspace at the start of the line below a block moves into the block and deletes nothing.
• Tab: inside a block, Tab indents the code. To leave with the keyboard, press Escape and then Tab.

Links

A link can point to a web address, to another document, or to a media file. All three are written into the text in a way that survives renaming and moving.

Link to another document

1. Select the words that should be the link, or put the cursor where the link should go.
2. Choose Link to document… in the toolbar. The dialog Link to document opens.
3. Type in Find a document. The box searches titles and words in the text. Use the arrow keys and Enter, or click a result.

Or drag a document from the tree into the text.

Expected result: the link text is the document’s title, or the words you selected. Behind it, the Markdown holds lake://<id>, the document’s ID. Because the link uses the ID, it keeps working when you rename or move either document.

Two messages can appear under the editor:

• “Linked to a draft: the link works once it’s published”. The target is not published yet. Publish it too.
• “A document can’t link to itself”.

If a linked document is later moved to the trash, the link points nowhere until you restore the document. The home page lists documents with such links under Needs attention, and Review all opens them as a list.

Link to a web address

Select the words, choose Create link, and type the address. Use the full address, starting with https://.

Add an image or a file

Open the Media tab in the right column. Then do one of these:

• Drag a picture from the panel into the text. It becomes a block next to the paragraph you dropped it on.
• Drag a PDF or Office file into the text. It becomes a link with the file’s title.
• Drag a file from your computer straight into the text, or paste a copied image. It is uploaded first, then a window opens where you describe it.

Every image needs Alt text before it can be used. If you drop an image that has none, the window Describe this image opens. Fill it in and choose Done. See The media library.

In the Markdown, images and files are written as asset://<id>, and the editor shows the real picture. This also works for images that are not published yet.

Autosave

You never press a save button. The editor saves 1.2 seconds after you stop typing. The status line above the page shows where you are:

Saving writes a draft only. It does not change what is published.

If you press Publish, the editor saves first, so what goes out is what you see.

Edit locks

Two people editing the same document would overwrite each other. So the CMS gives each open document to one person at a time.

• When you open a document, you take its edit lock. The lock is renewed every 30 seconds while the document is open. If you close it or lose your connection, the lock runs out after two minutes. (The setting Documents:LockSeconds changes this.)
• In the tree, a document someone else is editing has a lock icon. Hovering it says “Being edited by Ada”.
• If you open such a document, the dialog Someone is editing says “Ada is editing this document right now. If you take over, their next save will be refused.” Choose Open read-only to read it, or Take over to start editing.
• If someone takes the lock from you, the dialog Editing was taken over appears. Choose Reload latest. Changes you made since your last save were not saved.
• A document that someone else is editing cannot be moved to the trash.

If the page shows “Someone saved a newer version of this document. Reload to continue; your latest unsaved changes will be lost.”, choose Reload. This happens when two windows have the same document open.

The ID, the file name and the slug

Each document has an ID, a 26-character code shown below the body as ID 01M5YPMJRG2SN2C75GJWV9DAWF. Choose the copy button to copy it. You can paste an ID into the search box to find the document (Search). Developers use the ID to bind a site to this document.

Where the document sits in Git is decided by its folder and its file name. You never type a file name:

• Until the document is first published, the file name follows the title. “Fleet services” becomes fleet-services. If that name is taken in the folder, the CMS adds -2, -3 and so on.
• After the first publish, the file name stays the same, even if you change the title. A stable path keeps the Git history readable.
• Slug: a document can carry a slug in its settings, a short URL-friendly name for sites. The editor does not show it. It is kept as it is when you save, and it can be set by importing Markdown with a slug field (Importing content).

Paths never identify a document. Links use the ID. You can rename and move freely.

Rename and move

• Rename: open the document’s menu in the tree and choose Rename. The title is selected, so type the new one.
• Move: choose Move… next to the folder path above the document, or Move to… in the tree menu, and pick a folder. Or drag the document onto a folder.

If something goes wrong

What’s next

• Put the document in a folder and give it tags: Folders and tags.
• Add pictures: The media library.
• Make it visible to sites: Publishing.