JavaScript API

When to use it

Use this API when the published document needs to do more than render content and must interact with external code.

• send page views and other signals to analytics
• open a section, API page, or anchor programmatically
• react to route, language, and render lifecycle changes
• use built-in search without opening the default search UI
• connect the exported file to custom buttons, widgets, and section scripts

Entry point

The public object is available in the browser as window.OneFileDocsViewer.

const api = window.OneFileDocsViewer;

api.onReady(({ state, page }) => {
  console.log("ready", state.language, page?.title);
});

Do not depend on the internal window.viewer object. For integrations, only window.OneFileDocsViewer and the methods described in this guide should be treated as stable.

Core methods

The API has three main capability groups: event subscriptions, state reads, and control commands.

For subscriptions, use on(), off(), once(), and shortcuts such as onReady(), onRouteChange(), and onError().

For reading current state, use getState(), getCurrentPage(), and getPages().

For controlling the exported file, use navigate(), setLanguage(), and search().

const state = api.getState();
const page = api.getCurrentPage();
const pages = api.getPages();

api.navigate({ itemId: "guide", anchorId: "installation" });
api.setLanguage("ru");
const results = api.search("installation", { limit: 5 });

navigate() accepts either a hash string or an object with itemId, pageId, and anchorId. search() returns results and does not open the default search UI.

Events

The API exposes event constants under api.events and sends event objects shaped like { type, timestamp, ...payload }.

These are the main events most integrations care about:

• init after data load and base UI setup
• ready after the first successful start page render
• routeChange when the page view changes
• anchorChange when only the current page anchor changes
• languageChange after a language switch
• pageRender after each page render
• error for diagnosable exported file errors

Additional events are available for search, copied links, mobile panels, and section scripts. These are useful for analytics and debugging more advanced integrations.

Common scenarios

The most common uses are analytics and external navigation control.

api.onReady(({ state }) => {
  trackPage(state.route.hash, state.language);
});

api.onRouteChange(({ to, state }) => {
  trackPage(to.hash, state.language);
});

document.getElementById("switch-to-ru")?.addEventListener("click", () => {
  api.setLanguage("ru");
});

If you need to open a page from custom UI, call navigate(). If you need a custom search flow, call search() first and then pass the selected href into navigate().

Contract boundaries

For safe integrations, depend on the public methods, the event payload shapes, and the data returned by getState().

Do not depend on internal DocumentationViewer fields, the DOM structure of the exported file, or internal rendering methods. Those implementation details may change without compatibility guarantees.