Skip to main content

How to create and import Guides

Create a Guide in PlusPlus and keep it current: write Markdown in the built-in editor, import a ZIP or a Google Doc, publish new versions, and control what learners on older versions see.

Written by Michael Wallace

As an admin, organizer, or content owner, you have a technical tutorial you want to publish in PlusPlus as a Guide. You can write it in PlusPlus, import a Markdown package, or import a Google Doc — and later replace its content with a new version.

Before you start, make sure Guides are enabled in your instance.

The built-in Markdown editor and the Versions tab are currently in beta. If the create page shows no Guide Source section and no Versions tab, they are not enabled for your instance yet. Use the import route below instead.

Create a Guide

  1. From Content, select New and choose Guide.
    The create page opens. You can also start from the admin dashboard, MyHub, or a channel's Add content menu. Starting from a channel fills in that channel for you.

  2. Write the tutorial in Guide Source.
    Each level-2 heading becomes a step, and the outline on the left lists them as you type. Select text to open a formatting menu, or turn off Render Markdown to edit raw Markdown with syntax highlighting.

  3. Add any images in the Images panel.
    Select Add images, then select a thumbnail to insert it into the source. Images upload when you save, up to 10 MB each and 25 per save. Duplicate file names get a numeric suffix. Images cannot be renamed or removed from this panel.

  4. Check the Title and Description under Guide Details.
    PlusPlus fills these from your first level-1 heading and the text beneath it, and stops updating them as soon as you edit either field yourself.

  5. Set the Guide's channel, duration, tags, access and notifications on the Settings tab.
    You can also mark the Guide as inline so it is only reachable through tracks it is added to.

  6. Select Publish.
    The Guide's detail page opens. Publish & Duplicate and Publish & Bulk Duplicate are available from the same menu.

You can now assign the Guide or add it to a track.

Import a Guide

Import a prepared package instead of writing in PlusPlus. The import dialog opens when you add a new Guide from inside a track, and whenever you import a new version.

  1. Prepare your content.
    Either zip a Google Codelabs-formatted Markdown file with its assets, or author the tutorial in Google Docs. See Preparing a Markdown package below.

  2. Open the import dialog.
    From a track, add a new Guide. To replace an existing Guide's content, open the Guide and select Import new version from its settings menu, or use the three-dot menu on a track item card.

  3. Select Markdown (ZIP) or Google Docs.
    ​Google Docs only appears when the Google Drive integration is turned on. You may need to sign in to your Google account first.

  4. Select your file, then select Import.
    Importing can take a few minutes. A new Guide imported from a track opens its edit page. A new version opens the Guide's detail page, and the version goes live as soon as it builds.

Go deeper

Preparing a Markdown package

Zip the Markdown file together with its assets. PlusPlus selects one Markdown file from the package:

  • A root-level index.md wins, whatever its capitalization.

  • Otherwise the least-nested .md file wins, and where files tie on depth the first in character order is used. Capitals sort ahead of lowercase.

  • README.md is never selected, at any depth.

  • The extension must be exactly .md.

A package with no usable Markdown file fails with No valid markdown files found in the guide ZIP file. Any file or folder whose name starts with a dot rejects the whole package with Guide ZIP file must only contain files with relative paths.

The import dialog accepts packages up to 100 MB. The Developer API does not enforce that limit.

PlusPlus reads the package's metadata to fill in the Guide's name, description, duration and tags. This happens only while the Guide has no live version, so later versions do not overwrite details you have edited. On the create page the first save is also the first publish, so metadata in the file can overwrite a Title and Description you typed by hand.

Whoever imports the file becomes the Guide's Maintainer.

Google Docs imports

To turn on the Google Drive integration, go to Settings > Integrations > Storage, turn on Enable Google Drive integration, and save your settings.

A Google Doc is read once, at import. Edits you make in the Doc afterwards do not reach PlusPlus until you import it again.

Importing the Doc again creates a new version from the Doc's current contents, which does not include any changes made to the Guide inside PlusPlus. Pick one place to edit and stay there.

The Versions tab

Every version of a Guide is listed on the Versions tab with its status, when it was last updated, and who published it. Import Zip file imports a new version without leaving the tab.

Two columns describe the version's reach, counted for that version alone rather than the Guide as a whole:

  • Assignments: active assignments against that version. Dropped and expired assignments are excluded; completed ones are included.

  • Engaged people: learners who have started that version and not yet finished. A learner counts as started once they move past the first step, so opening a Guide and stopping does not count.

Select exactly two successfully built versions and choose Compare to see a word-level diff of their Markdown source, including front matter. The comparison opens in a drawer, with the older version on the left, and can be shown unified or side by side.

Publishing a new version versus updating the current one

When you have unsaved changes in the editor, the main button becomes Publish New Version, which creates the next version and leaves the existing one untouched. The menu also offers Update Current Version, which rebuilds the loaded version in place so that learners already on it see the change on their next page load.

Prefer Publish New Version while learners are working through the Guide. If an in-place rebuild fails, learners pinned to that version cannot launch it until the version is saved successfully again.

What learners see when you publish a new version

Learners stay on the version they started. Inside the Guide, a banner tells them a newer release is available and offers Switch to the latest release. Dismissing the banner leaves a small marker they can use to switch later, and switching can be undone. The Guide checks for new releases when it opens and periodically while it is open.

New assignments are always made against the latest version.

Managing and tracking Guide assignments

You can see who has been assigned a Guide and how far they have progressed, and update their assignments. Learn more.

See also

Related Articles
Did this answer your question?