Import & Export
Overview
Documents, Answers and Snippets each have an Import & Export screen:
- Documents → Import & Export for your documentation tree.
- Answers → Import & Export for your knowledge base. A spreadsheet of questions and answers becomes a set of answers in one go.
- Manifest → Import & Export for snippets.
On any of them you can:
- Import a spreadsheet to add documents, answers or snippets all at once, or to update titles, excerpts and categories across the whole list.
- Export them as a spreadsheet (CSV) to edit or keep, or as a JSON file to copy them to another Dirigible site.
You can also get there from the Import and Export buttons beside Add New at the top of the Documents, Answers or Snippets list.
You need an Editor or Administrator account. Importing also needs permission to upload files, because featured images are downloaded into the Media Library.
Export
- Go to Documents → Import & Export, Answers → Import & Export or Manifest → Import & Export (snippets) and stay on the Export tab.
- Choose Spreadsheet (CSV) to open the file in Excel, Numbers or Google Sheets, or JSON to import it on another Dirigible site.
- Turn on Include drafts and private ones if you want those too. Off, the file holds only published ones.
- Select Download export file.
Import a spreadsheet
The quickest start is Download a blank spreadsheet on the Export tab: it has every column with the right header. Or export what you have, edit it, and import it back.
- Fill in one row per document, answer or snippet. Only Title is required. Leave out any column you don't need.
- Save it as CSV (in Excel: File → Save As → CSV UTF-8).
- Go to the Import tab and drop the file on the box, or select Choose a file.
- Nothing changes yet. You see every row with what will happen to it:
- New: it isn't on this site, so it's added.
- Update: it's already here and the row has changes. The list names them (Excerpt, Categories…).
- Skip (No changes): it's already here and nothing differs.
- Error: the row can't be imported, for example because its title is empty.
- Untick any row you don't want brought in.
- Choose what happens to ones already on the site: Update it from the file, or Leave it as it is (only add new ones). If the file has no Status column, choose whether new ones are added Published or as Drafts.
- Select Import. Keep the page open until it finishes. If it's interrupted, open the page again and select Resume import: nothing is added twice.
Documents columns
| Column | What goes in it |
|---|---|
| Title | The document's name. |
| Path | Where it sits in the tree: the web addresses of its parents and its own, joined by /, like getting-started/overview. A top-level document is just its own web address. This is how an existing document is found, so two documents called overview under different parents each update their own. |
| Parent | The parent's path (getting-started) or its name. Leave it out when the row has a Path: the parent is read from it. A parent that's new in the same spreadsheet is found too. |
| Content | Plain text (a blank line between paragraphs) or HTML. It goes inside the document's Document block. |
| Excerpt | The summary shown in listings. |
| Featured image | The web address of an image. It's downloaded into the Media Library. An image already in this site's Media Library is reused. |
| Featured image alt text | Describes the image for screen readers. |
| Order | A number, for the order of pages under one parent. |
| Status | Published, Draft, Pending or Private. |
| Slug | The last part of the document's web address. Leave it out to have it made from the title, or from the Path. |
An export writes every document with its Path and its parent's path, so a whole tree comes back as it was on another Dirigible site, parents and all.
Answers columns
| Column | What goes in it |
|---|---|
| Title | The question. A column called Question works too. |
| Content | The answer. Plain text works: leave a blank line between paragraphs. A column called Answer works too. |
| Excerpt | The summary on answer cards. |
| Categories | Names separated by ` |
| Status | Published, Draft, Pending or Private. |
| Slug | The last part of the answer's web address. Leave it out to have it made from the title. |
Snippets columns
| Column | What goes in it |
|---|---|
| Title | The snippet's name. |
| Content | Plain text (a blank line between paragraphs) or HTML. It goes inside the snippet's Snippet Page block. |
| Excerpt | The summary shown in listings. |
| Featured image | The web address of an image. It's downloaded into the Media Library. An image already in this site's Media Library is reused. |
| Featured image alt text | Describes the image for screen readers. |
| Featured Video | The address of an MP4 that's already in this site's Media Library. Videos aren't downloaded: one from anywhere else is left off, and the preview says so. Upload it, then pick it in the editor. |
| Order | A number, for lists sorted in a custom order. |
| Status | Published, Draft, Pending or Private. |
| Slug | The last part of the snippet's web address. |
A snippet's parent (under Page Attributes) isn't imported or exported. It only sorts the admin list, so set it in the editor if you use it.
Column headers can be in any case, and a small typo is fine: the preview tells you how each header was read, and lists any it ignored.
Updating ones that are already on the site
A row updates an existing answer or snippet when it has the same web address (Slug), then the same title. A document is found by its Path first, then by its web address or title under the same parent. The preview shows which one each row matched and why.
Only what's in the spreadsheet changes. An empty cell never clears anything, so you can import a sheet with just titles and new categories without touching any content. To clear a field, edit that document, answer or snippet.
Updated ones keep their status and web address.
Copy documents, answers or snippets to another Dirigible site
Export as JSON on one site and import the file on the other. A JSON file carries the content exactly as it was written, including HTML and code in Custom HTML blocks, plus excerpts, categories, order, parents and featured images. Featured images are downloaded from the site the file came from, so that site needs to be online. Featured videos don't come along: upload them on the new site, then pick them in the editor.
Undo an import
When an import finishes, select Undo this import. It deletes what that import added (documents, answers, snippets, downloaded images and new categories), and puts everything it updated back exactly as it was. Anything edited after the import is left as it is and listed, and an image or category that something else now uses is kept. Undo stays available for 7 days.
