ondocs

Reference

Upgrading

The options each minor version renames, old name to new, and the defaults that change with them.

Before 1.0, a minor version can rename an option. The old name keeps working until the next minor version, and says once what it is called now: in the build's output for the plugins, in the server's log for the endpoint, in the terminal for the CLI, and in the browser's console for the dialog.

0.9: one name per option

0.9 gives each option one name across createAskHandler, AskDialog, mountAskDialog, the script tag, the plugins and the CLI. The old names still work in 0.9, with a warning, and 0.10 removes them.

WhereBefore 0.9From 0.9
The plugins' dialog and dialog.locales, mountAskDialog, window.Ondocs.mount()buttonLabel: 'Ask', buttonLabel: falselauncher: 'Ask', launcher: false
The script tagdata-button-label="Ask"data-launcher="Ask"
AskDialogtheme="system"theme="auto"
createAskHandlermaxContextChars: 6000retrieval: { maxContextChars: 6000 }
ondocs init--name "Acme Docs"--site-name "Acme Docs"

launcher takes the same values buttonLabel did, and true for the default label. When a site sets both names, the new one wins.

Two defaults change in AskDialog, so that it matches the plugins and the script tag:

  • The shortcut is ⌘I, or Ctrl+I outside macOS. It was ⌘K. ⌘K stays with the site's search, and text fields keep ⌘I for italic. Pass shortcut="k" to keep ⌘K, as on a site whose only search is this dialog.
  • theme="auto", the default, follows data-theme on <html>. A page with data-theme="dark" gets the dark dialog whatever the system's setting, as with the plugins and the script tag. A page without one still follows the system, and theme="light" or "dark" still pins one.

To find the old names in a site:

Terminal
git grep -nE 'buttonLabel|data-button-label|theme="system"|maxContextChars|init --name'

maxContextChars is fine where it is already inside retrieval.