Quillet
Menu
Menu

Writing a document

7 min read

Write a Markdown document in the dashboard's Visual editor or in its Source, put pictures in from the media library, and save each change as a version that readers do not see until you publish it.

Why the editor stores Markdown and saving is not publishing

Guides, articles and help pages are mostly prose, and prose is easiest to write in an editor that looks like the page. What the CMS stores, though, and what the site turns into a page, is Markdown: plain text that the site's own code renders in the site's own design. The Visual editor lets you write without thinking about Markdown. The Source view is there for the moments when you need to see exactly what will be stored. Both edit the same text, so you can switch between them at any time.

Saving is separate from publishing for the same reason a draft is separate from a sent letter. You can save half a paragraph, close the tab and finish tomorrow, and readers keep getting the last published version until you decide otherwise.

What the editor shows, stores and saves

The two views

A Markdown document opens on Visual, with Source beside it.

  • Visual shows headings, lists, links and pictures as they will look. Its toolbar starts with a Text style select (Paragraph, Heading 1 to Heading 6), followed by Bold, Italic, Strikethrough, Code, Link, Image, Image description, Bulleted list, Numbered list, Task list, Quote, Code block, Table, Divider, Undo and Redo. Inside a table, a small bar offers Add row above, Add row below, Add column before, Add column after, Delete row, Delete column and Delete table.
  • Source shows the Markdown itself, with a live preview beside it. Preview only hides the text and widens the preview. On a narrow window the two are tabs instead: Write and Preview.

Expand gives the editor the full width of the page and hides the panel on the right. Collapse, or Escape, brings the panel back.

What is stored

Every keystroke in Visual is written back as plain GitHub-flavoured Markdown. A picture from the media library is stored as the file's address on the CMS, such as /d/v1/handbook/assets/<id>, so the CMS records that this document uses that file. The media library then lists the document under the file's Used by, and the file cannot be deleted while the document uses it.

Some Markdown has no Visual form: raw HTML, an HTML comment, footnotes, maths and definition lists. A document that contains any of them opens in Source, with a sentence that names what was found, and Visual is unavailable for that document. Nothing in it is rewritten.

Saving and versions

Save, or ⌘S on a Mac and Ctrl+S elsewhere, keeps a new version of the document. The earlier versions stay, and History lists them all, with who saved each one and when. A save changes nothing for readers. While there are unsaved changes, Publish stays unavailable, with "Save first" under it, so you can never publish anything other than what you saved. Publishing and history covers what happens next.

Three cards sit beside the editor:

  • Details: the Title, which is how the document appears in lists and search; its Order ("Lower comes first, within its folder"); and its Tags, separated by commas.
  • Publishing: Searchable, which decides whether the site's search may return this document. Inherit takes the folder's setting. Search index explains what the search holds.
  • Change note: a Message that History shows beside this version. It is optional, and worth a few words.

If you try to leave with unsaved changes, the dashboard first asks Leave without saving?.

How to

Create a document

  1. In Content, press New and choose Document.
  2. Type a Key: lowercase, with slashes for folders, such as guides/onboarding. The key is the document's address. It cannot contain capitals or spaces.
  3. Under Type, choose Markdown.
  4. Leave Locale on the project's default locale, unless you are writing in another one from the start.
  5. Press Create document. The new document opens empty, as a Draft.
  6. Under Details, type a Title so the document reads well in lists.

Write and format

  1. Type in Visual. To turn a line into a heading, put the cursor in it and choose Heading 2, or another level, in the Text style select.
  2. Select words and press Bold, Italic or another button to format them.
  3. To link to another website, select the words and press Link. Type the full address in Address, starting with https://, and press Apply. Remove link takes a link off again.
  4. To link to a page on your own site with a short address such as /guides/welcome, switch to Source and write the link there: [the welcome guide](/guides/welcome). The Visual Link box accepts only http, https, mailto and tel addresses.

Put in a picture

  1. In Visual, put the cursor where the picture goes and press Image.
  2. Choose an image lists the project's images. Narrow the list with Search by name, or press Upload to add a new file from your computer.
  3. Select the picture and press Choose. It appears in the text, with the file's own description as its alt text.
  4. To change what a screen reader says for this picture, select it and press Image description. Fill in Alt text (leave it empty for a decorative picture) and, if you like, Title, then press Apply.

You can also drop an image file onto the Visual editor, or paste one in. The file is uploaded to the media library first, and it appears in the text once the upload has finished.

Save the change

  1. Under Change note, type a line about what you changed.
  2. Press Save, or ⌘S or Ctrl+S. "Saved." appears above the editor. The status in the page bar reads Draft for a document that was never published, or Changed since published for one that was.

Rename a document

  1. In the tree, select the document and open its menu with ⋮ (or Shift+F10).
  2. Choose Rename and type the New key.
  3. Press Rename. The current content of every locale is saved under the new key as a new draft, with the change note "Renamed from" and the old key, and the old key is deleted.
  4. Publish the document under its new key, in every locale that was published before.

Delete a document

  1. In the tree, select the document and open its menu with ⋮ (or Shift+F10).
  2. Choose Delete. The dialog says which locales will go.
  3. Press Delete document. The history is kept, so writing the same key again brings the document back where it left off.

Limits

  • Private files cannot be used in Markdown. The picker shows them with "Private files can't be used in Markdown; make it public or use a component field.", and anything you upload from the picker is uploaded as public.
  • The Visual Link box takes only full http, https, mailto and tel addresses. Write short links within your own site in Source.
  • The Visual editor does not support Markdown beyond the GitHub-flavoured set (footnotes, maths, definition lists, raw HTML). A document that uses any of it opens in Source only.
  • The first edit in Visual can rewrite how some Markdown is spelled, such as list markers, emphasis and table padding, without changing the words. The editor tells you before that happens. If the exact spelling matters to your team, write in Source.
  • There is no collaborative editing, and there are no comments. Two people typing in the same document at once do not see each other, and the second to save is told so; see When two people edit.
  • A document cannot be renamed or deleted while another document uses it. The menu says so; remove the use first.

Last updated