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 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](../reference/configuration.md#export-to-a-folder).

<!-- wikitool:toc -->
## Contents

- [Pick the pages and the format](#pick-the-pages-and-the-format)
- [Set it up](#set-it-up)
- [What a run does to the folder](#what-a-run-does-to-the-folder)
- [Export after every publish](#export-after-every-publish)
- [Convert the pages with a program of your own](#convert-the-pages-with-a-program-of-your-own)
- [What does not come back in](#what-does-not-come-back-in)
- [Related](#related)
<!-- /wikitool:toc -->

## Pick the pages and the format

- **Which pages.** Only what a target's `include` selects is written; there is no "everything". 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. Try a selection with
  `tools/wikitool search --field tags=shared` first.
- **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.

  Whether a Microsoft 365 tenant indexes `.md` files for Copilot is not settled for every tenant.
  Try a small `markdown` target first; if the tenant 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, outside every `intake`
   folder and outside `backup.target`.
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:

   ```json
   {
     "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.
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 pages come from. Publish first.

## What a run does to the folder

The folder holds the pages 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 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`:

```json
{
  "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`, 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](../reference/configuration.md#export-to-a-folder)
- [Export commands](../reference/commands/exports.md)
- [Export guidelines to captured repositories](export-guidelines.md) - the other export, one file
  pushed into a repository
- [Back up to a synced folder](back-up-to-a-synced-folder.md) - the same kind of folder, for the
  backup instead