Skip to main content

Split a topic and create a TOC

Split by H1 / H1-H2 / H1-H3 / H1-H4 · Split a Topic File... · Topic Splitter (Batch)...

Kaizen Plugin ⚡ tab → Topic Splitter group

Splitting a topic file is a quick and easy way to create a new manual from a single topic file. You can split a topic files by H1-H4.

To split a topic file into separate topic files based on the heading level, and generate a corresponding TOC-file:

  1. Open the relevant topic.
  2. Click Split by H1 to split by heading level 1, etc.

The topic files and the corresponding TOC are created.

Headings wrapped in a MadCap concept, micro content, or div element are recognized too - the wrapper is kept intact and moved into the split file. Content before the first heading is kept as an introduction in the first split file.

Split a topic without opening it​

Large topics can be slow to open in the editor. To split a topic straight from disk:

  1. Click Split a Topic File... in the Topic Splitter group.
  2. Pick the topic file, choose the heading depth (H1 .. H1-H5), and confirm.

The file is split as it is saved on disk, so save any unsaved changes first.

Split several topics with custom file names (batch)​

To split more than one topic in one run, or to control the names of the generated files:

  1. Click Topic Splitter (Batch)... in the Topic Splitter group.

  2. Pick one or more source topics and an output folder.

  3. Choose the heading level(s) - or enter a CSS selector (e.g. p.commandPrefix, h1, h2, div[class^='cmd']) to split on arbitrary boundary elements instead - and, optionally, edit the file name pattern:

    • {heading} - the heading text
    • {i} - a running number (0, 1, 2, ...)
    • {source} - the source file name

    The default pattern {i} -{heading} matches the classic splitter naming (0 -My Heading.htm). Use just {heading} to drop the number prefix. If a pattern produces duplicate names, an index is appended automatically - files are never overwritten silently.

  4. Review the output file names in the preview list, then click Create files.

The last-used pattern is remembered for the next run. Existing files are only overwritten after one single confirmation for the whole batch.

TOC entry titles​

By default, generated TOC entries use [%=System.LinkedTitle%], so the TOC always shows the current topic title. Untick Use [%=System.LinkedTitle%] for TOC entries in the batch form to write the literal heading text instead (inline variables are kept in [%=VarSet.Var%] syntax; empty headings still fall back to System.LinkedTitle). The choice is remembered and also used by the Split by H1..H5 buttons.

Other topics, snippets and TOCs that link to the topic being split would otherwise keep pointing at the old file. After a split, the splitter offers to update links in other files: links with a #bookmark are re-pointed at the split file that contains the bookmark, links without a bookmark go to the first split file, and .fltoc entries are re-pointed too. Bookmarks that cannot be found are listed so you can check them manually.

Command line (KaizenCommander)​

Topics can also be split headlessly:

KaizenCommander -split "C:\...\topic.htm" h2 "C:\...\outputFolder" [-toc "C:\...\tocFolder"] [-pattern "{i} -{heading}"] [-overwrite] [-literaltitles]
  • The source can be a single file or a folder (all .htm/.html files in it).
  • Selectors: h1 .. h6 (split by H1 .. H1-HN), an element name (p), name.class (p.commandPrefix), or any CSS selector ("h1, h2").
  • -toc writes a TOC-<source>.fltoc per source file into the given folder (or to an exact .fltoc path for a single file).
  • -pattern uses the same tokens as the batch form.
  • Without -overwrite, existing files are skipped.
  • -literaltitles writes the heading text as TOC entry titles instead of [%=System.LinkedTitle%].

Script function (FlareScript)​

Scripts that compile against KaizenPlugins.dll can call the split engine directly:

//SplitEngine.SplitTopic(sourceFile, selector, fileNamePattern [, options])
var files = SplitEngine.SplitTopic(@"C:\...\topic.htm", "h1", "{h1}_{i}");
var cmds = SplitEngine.SplitTopic(@"C:\...\big.htm", "p.commandPrefix", "{heading}",
    new SplitOptions { OutputFolder = @"C:\...\out", Overwrite = true, TocPath = @"C:\...\TOCs\big.fltoc" });

The selector accepts the same forms as the command line; the pattern uses {heading}/{h1}, {i} and {source}. The function returns the written file paths and throws an exception (with the reason) if the topic cannot be split.

Still stuck? Contact support