Getting Started with Paligo

Table of Contents

The Markdown Editor

The Markdown Editor is a light-weight editor made for Contributors to quickly create drafts of content. It can be used by any type of contributor, full Authors as well, but because of the popularity of markdown formats among developers, it is especially designed with developers in mind.

Although it's called Markdown Editor, it is really a variant of markdown called AsciiDoc. While not as powerful as XML, as the main editor uses, it is more versatile than regular markdown, and can therefore be used to create a lot of content that Paligo then converts to proper XML for the Technical Author to work further on.

The Contributor writes the draft content in a plain text format, getting a live preview of the result:

Warning

Only use the Markdown Editor for creating drafts of new content, not to update previous existing content, since it does not have the ability to preserve some of the more advanced features in Paligo content, like filtering, variables, reuse text and translation versions.

Should the topic pre-existing content, or content not supported, the user will be notified in a note/warning at the top, and can choose to close without saving if uncertain.

An Author can still prepare a topic with some pre-written content, if so desired, of course.

Editable Topics

There are two types of topics that are editable in the Markdown editor:

  1. Empty topics: I.e topics just created and that hasn't been edited before in the Paligo main editor.

  2. Marked topics: This is when an Author has specifically marked a topic as editable in the Paligo editor, using the toggle.

AsciiDoc Format

The syntax of the AsciiDoc markdown format is very easy to learn, and makes it easy to quickly create drafts.

For example, to write an ordered list you just precede each item with a dot. And to make that a procedure just add [role='procedure'] above it.

Code blocks are easily added with just dashes before and after the code, and then a bracket marker above to specify the language:

See the Cheat Sheet for more details.

Typical Contribution Workflow

The idea is to get contributions from users other than full Authors (usually users with the "Contributor" license type), and there are several ways to go about this. But this may be a typical workflow:

  1. The Author creates a number of topics to get contributions from a Contributor, either just giving them a topic name, but leaving them empty, or adding some pre-written content, and then marking them as editable by a Contributor:

    Note

    Do not save after changing to make it editable by contributors, as that will change it back. If you need to save, do so before setting this.

  2. If they are to be viewed in context of an entire publication, they can be added to the publication in the Structure View in their proper nesting structure.

    Or a separate "dummy" publication can be created just to send the batch of topics as a whole for an assignment.

    Of course, if it's just one topic, no publication is needed.

  3. Create an assignment for the topic or the publication to the Contributor, in the Project Planner or directly on the context menu of the publication/topic in the Content Manager.

  4. When the Contributor clicks the link in the assignment email, the Contributor view opens, and the Contributor will see which topics are editable, and can click them to open the Markdown editor and add the content:

  5. When the Contributor has added all the content and saved, it is converted to Paligo XML format.

  6. The Contributor updates the assignment to Completed, and the Author gets an email notification.

  7. The Author can now proceed with polishing the content and adding any advanced features like filtering, reuse text, variables, translations, etc, as needed.

Note

A Contributor user must have had an assignment for topics to edit in the Markdown editor. However, an Author can always open a topic in the Markdown editor by selecting it from the context menu in the Content Manager:

To be able to open it there, the topic must still be either empty (not edited before in the main Paligo editor, or marked as editable in the Markdown editor.