chemenu/docs/how-to/export-to-a-synced-folder.md

Export to a synced folder

Give a reader outside the repository a read-only version of part or all of kb/: the selected pages, written as files into a folder - typically one a sync client such as OneDrive uploads, so that a Microsoft 365 tenant can index them. The export is derived. It is regenerated from the committed pages on every run, nobody edits it, and nothing in it flows back into the wiki. What the settings look like: configuration reference.

Contents

• Pick the pages and the format
• Set it up
• What a run does to the folder
• Export after every publish
• Convert the pages with a program of your own
• What does not come back in
• Related

Pick the pages and the format

• Which pages. Only what a target's include selects is written. "include": "all" selects every page, also one that lies directly under kb/, and no generated file. Otherwise a selection is a list of search predicates that must all hold - tags=shared, kind=system, !draft - and a page that fits any selection of the target is exported: "include": [["tags=shared"]]. Try a selection with tools/wikitool search --field tags=shared first. A missing or empty include is an error, not "all". With "all", every page you add later goes into the export too - on a target with after_publish at the next publish.

• An entry point. The folder holds the pages only. "index": true adds index.md in the root of the folder and an INDEX.md per collection, so someone who opens the folder finds the collections, their areas and the pages with their summaries by following links. The files list what the target exports and nothing else, and the link text is the page's title.

• Which format. Two ways, equally valid:

  • markdown writes the pages as .md files. It needs nothing but the folder.
  • command hands those files to a converter of your own and exports what it produces - Word documents with pandoc, say.

  In the one tenant checked so far (10.0.0), Microsoft 365 Copilot found the .md files of a markdown target in OneDrive and used them. Tenants differ, so start with a small markdown target; if yours does not pick the files up, the same pages go through a command target as a format it does.

Set it up

1. Pick the folder: a folder inside the synced folder, for example C:\Users\<you>\OneDrive - <company>\Chemenu-Lesefassung. It must be empty or not exist yet, and it must lie outside the instance, outside every other export target and every intake folder, and apart from the folders the backup writes into: it may not be, lie in or contain <backup.target>\git or the backup's machine folder, nor lie in another machine's folder or a bare repository. A folder beside them is fine, so one synced folder can hold the backup, an intake folder and the export, with the export in <OneDrive - company>\Chemenu\Export (the layout).

2. Write the export section into .wikitool-local.json at the root of the instance - by hand, since its fields decide what leaves this machine and which program runs, and config set refuses them:

   {
     "export": {
       "targets": {
         "shared": {
           "handler": "markdown",
           "path": "C:\\Users\\<you>\\OneDrive - <company>\\Chemenu-Lesefassung",
           "include": [["tags=shared"]],
           "frontmatter": "summary",
           "links": "relative",
           "after_publish": false
         }
       }
     }
   }
   

   frontmatter decides what follows the export marker in each file: minimal nothing, summary (the default) the title, type, summary and modified date, full the page's whole frontmatter. links: relative (the default) turns a link to an exported page into a relative Markdown link; links: text leaves the page's name. A link to a page that is not exported is always plain text. The index files link relatively whatever links says.

   To put the whole of kb/ into the folder with an entry point, write "include": "all" and "index": true instead of the include selection above.

3. Tell the agent:

   Export the pages.

   The agent runs tools/wikitool export run. It reports per target which pages are new, which changed and which were removed, and how many stayed as they were. Name a target to run only that one: tools/wikitool export run shared.

4. Check it: tools/wikitool doctor. The export line lists the targets; a FAIL there names what is wrong with the section.

The export reads the committed pages. A kb/ or types/ with uncommitted changes is refused, so every file names the commit its page comes from. Publish first.

What a run does to the folder

The folder holds the pages, the index files if the target asks for them, and one file of the stack's own, .wikitool-export.json, which lists what the last run wrote.

• Only its own files. A run removes a file only when it is listed and no longer exported, and a folder only when the run created it. Anything else in the folder stays as it is.
• Nobody edits an export. A listed file that someone changed stops the target before anything is written, and the message names the file. Move or delete it and run again. A listed file that is missing is written again.
• A folder that is not an export is refused. A folder that holds files and no manifest is somebody's folder; the run writes nothing into it.
• An empty selection is an error. A run that finds no page does not delete the earlier export.
• An unchanged export stays untouched. A run that has nothing to change writes nothing, not even a modification time - the sync client has nothing to upload.
• A commit rewrites the files of the pages it touched. Each file names the last commit of its own page, so an ingest that changed three pages rewrites three files, however large the selection. A file of a page the commit did not touch changes only when its text does: a link to a page that has just entered the selection becomes a relative link, one to a page that left it plain text. The first run after updating to a version that brought this rewrites every file once.
• An index follows the pages. A collection's INDEX.md changes when one of its pages does, and index.md, which lists them all, with every commit to an exported page. Setting index back to false removes the index files at the next run and leaves every other file as it is. A page index.md in a collection, next to the generated INDEX.md, stops the target: a synced folder on Windows would make them one file.
• A growing selection needs no confirmation. New pages are reported as new; read the list before the sync client uploads them.

Targets are independent: one that fails is reported with its reason and the others still run; the command then exits 1.

Export after every publish

With "after_publish": true on a target, every tools/wikitool publish that committed refreshes it afterwards - with --no-push too, since the export reads the commit, not the remote. If that export fails, publish prints a WARN with the reason and still exits 0: the commit and the push stand. Fix what the line names and run tools/wikitool export run; another publish does not repeat it. A malformed export section stops publish before it commits, but only when some target sets after_publish.

Convert the pages with a program of your own

A target with "handler": "command" names an entry of commands:

{
  "export": {
    "targets": {
      "as-word": {
        "handler": "command",
        "command": "pandoc-docx",
        "path": "C:\\Users\\<you>\\OneDrive - <company>\\Chemenu-Word",
        "include": [["tags=shared"]]
      }
    },
    "commands": {
      "pandoc-docx": ["pwsh", "-NoProfile", "-File", "C:\\tools\\pandoc-docx.ps1"]
    }
  }
}

The pages are rendered into a staging directory first. The program runs without a shell, with stdin closed and a limit of 300 seconds, and gets two more arguments: the directory with the Markdown files and an empty directory for its output. On exit 0 the regular files it left there (below any subdirectory, symlinks left out and reported) become the content of the target; the manifest and all the rules above apply to them as to Markdown. Any other end - a non-zero exit, a timeout, a program that does not start - leaves the target exactly as it was and prints the end of the program's stderr. The staging directory is always removed.

What does not come back in

An export is never a source. Every Markdown file starts with a frontmatter block whose first key is wikitool_export - the index files too - and tools/wikitool raw accept and raw capture refuse a file that carries it. A converter may lose that key, so raw accept also refuses any file in incoming/ that is byte for byte one of the files in the manifest of a configured target - and warns, without refusing, when a target has no manifest yet or the export section is broken.

Related

• Configuration reference
• Export commands
• Export guidelines to captured repositories - the other export, one file pushed into a repository
• Back up to a synced folder - the same kind of folder, for the backup instead