Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Edit and save a topic

Change a topic in the visual editor or its source, watch the preview update as you type, and save it to your working branch.

  1. On the Files page, choose the topic or map.

    Files you changed on your branch are marked changed.

  2. Edit the topic on the Visual tab.

    Topics open looking much as they read, with the title, short description and body editable in place. The toolbar adds bold, italic, code and other formatting, links, bulleted and numbered lists, steps in a task, notes, code blocks, images and sections. Block settings sets who sees the block holding the cursor (release, product, feature, audience and the other filtering attributes) and a note's type. It opens beside the text, or at the bottom of the screen on a phone, and stays in view while you edit; the block it changes is outlined. Blocks shown only to some readers are outlined and labelled.

    Markup the visual editor does not edit directly, such as tables and reused content, appears as a locked block. It is kept exactly as it is; double-click it to change its XML. Saving writes back only the blocks you changed, so the rest of the file keeps its formatting.

    Maps, and topics the visual editor cannot convert and save back without changing them, open on the Source tab with a note saying why. Developers can switch to Source at any time to edit the DITA directly.

    The Preview tab, after Source, shows the page with your unsaved text. It is the staff view: everything is shown and conditions are marked. Under Show the page for, choose a value for any of the conditions the content uses (a version, product, feature, audience and so on) and choose Show to see only what readers with that combination see. Show everything goes back to the full staff view. Problems lists what validation finds in the file, the same as opend validate; see Validation diagnostics.

  3. Optional: check what a customer sees. Under the preview, on the Preview tab, choose an org and Open.

    The page opens with that org's products, features and version, as the docs site would show it. It shows your last save, not unsaved text. The link expires after 30 minutes and is logged.

  4. Optional: add a note about the change, then choose Save.

    The save is a commit to your working branch, and the page shows its short id. Your first save creates the branch from the main branch. Nothing is published.

Results

  • A save is refused, and nothing is saved, when the file is not well-formed XML. Fix the problem it names and save again.
  • Validation problems do not stop a save, but they stop you publishing.
  • If the file changed since you opened it, by another save or by a merge from the main branch, the save is refused so it cannot overwrite that change. Copy your text, reload the page, and apply it again.
  • After a save, the editor merges the latest main branch into yours. If that conflicts, it takes you to Resolve conflicts with the main branch.

Create a topic

Start a topic from a template and, optionally, add it to the navigation.

  1. On the Files page, under New topic, fill in the form.
    • Title: the topic's title.
    • File name: lowercase letters, digits and dashes. .dita is added.
    • Folder: where the file goes.
    • Type: concept (explains what something is), task (step-by-step instructions), reference (facts to look up) or a general topic.
    • Add to navigation: a map to add it to, or Not yet.
  2. Choose Create topic.

    The new topic, and the map if you chose one, are saved to your working branch in one commit, and the topic opens for editing.