Egenverk Docs Viewer · Documentation
The viewer
The viewer lives under Tools → Docs Viewer and is laid out like a repository page on GitHub: file tree on the left, the document on the right.
What is scanned
Docs Viewer goes through:
- plugins that sit in their own folder in
wp-content/plugins - every installed theme, in
wp-content/themesand any other registered theme folder - must-use plugins that sit in their own folder under
wp-content/mu-plugins
In each folder it picks up:
| Location | Files |
|---|---|
| The folder root | .md, .markdown, .mdown and .txt, such as README.md, CHANGELOG.md and readme.txt |
docs/ and its subfolders | The same formats plus .json, .js, .jsx, .ts, .tsx, .css, .scss, .less, .html, .htm, .xml, .yml, .yaml, .ini and .conf |
PHP files are never listed or read. Inside docs/, the folders node_modules, vendor, .git, bin and build are skipped, and the scan goes at most eight levels of subfolders deep. Folders without any such files are not shown. Docs Viewer's own folder is not scanned.
The index rebuilds automatically when plugins or themes are installed, updated or deleted, and when plugins are activated or deactivated. After changes made outside WordPress, click Scan for docs. After a scan, a status chip such as Scanned — 12 found shows how many plugins and themes with documentation were found.
Parts of the viewer
| Part | What it does |
|---|---|
| Top bar | The plugin and theme switcher, the Search all docs field and the Scan for docs button |
| Files | The files of the selected plugin, root files first and then the folders under docs/. The Filter files… box hides files whose names do not match |
| On this page | The document's level 2–3 headings, or 1–3 when it has no level-2 heading. Click one to jump to it. Shown when there are at least two |
| Preview | The rendered Markdown document. For other files the tab is called Rendered |
| Raw | The unchanged source, with a Copy button |
The switcher appears when more than one plugin or theme has documentation. When more than one kind is indexed, it groups its entries under Plugins, Themes and Must-use plugins. Opening a plugin shows its README first, if it has one.
No admin notices are shown on the viewer screen, so they never end up in the middle of a document. They show as usual on other admin pages.
Formatting
Markdown files and .txt files in the wordpress.org readme.txt format are shown formatted. Other files are shown as code and are never run.
The formatter covers what plugin documentation tends to use:
- headings, bold, italic and strikethrough
- lists, including nested lists
- tables with left, right and centre alignment
- blockquotes
- links, images and bare web addresses
- horizontal rules
- inline code and code blocks
Code blocks are highlighted for PHP, JavaScript, TypeScript, JSX, TSX, JSON, CSS, SCSS, HTML/XML, shell, YAML, SQL, diff and INI. The highlighter ships with the plugin and loads nothing from outside. Raw is always shown without highlighting.
Not supported: raw HTML in a document (shown as text, never run), reference-style links, footnotes, and headings underlined with === or ---.
Links and images in documents
Relative links work as on GitHub. A link to another document of the same plugin, or to a folder with a README, opens in the viewer. Links to a heading in another document open at that heading.
Relative images are shown when they are inside the plugin's own folder and are .png, .jpg, .jpeg, .gif, .webp or .svg. A relative link that does not point to a scanned document is shown as plain text, and an image that does not meet those conditions is shown as its alt text.
Search
Type at least two characters in Search all docs and press Enter. Search goes through every scanned document of every plugin, theme and must-use plugin and ignores case. The query is matched exactly as you type it, so even characters such as <div or %20 can be found. The field takes at most 100 characters.
Results show the plugin and file, with up to three highlighted lines per file. Click a result to open the file, or Close search to go back to the document. At most 100 files are listed; the viewer then says Showing the first 100 files. Refine the search to see more. and you narrow the query.
Links on the Plugins screen
Plugins with documentation get links on their row on the Plugins screen:
| Link | What it does |
|---|---|
| What’s new in X.Y | Shown after an update. Opens the changelog cut to the releases since the version you had |
| View Docs | Opens the plugin's documentation in the viewer |
| Changelog | Opens the plugin's root CHANGELOG, or else its readme.txt, at the section for the installed version, or at the Changelog heading when no section matches. Shown only when the plugin has such a file |
Docs Viewer's own row also has a Browse Docs link that opens the viewer.
What’s new needs a Markdown CHANGELOG (.md, .markdown or .mdown) or a readme.txt at the root. The cut changelog is shown under a note reading What’s new since followed by the versions, with a Show the full changelog link. The link disappears for everyone once an administrator has opened it, and otherwise after 30 days. If the plugin is updated again before anyone has read it, the changes of both releases are shown. Only plugins are tracked, not themes or must-use plugins.
The links are on by default. To remove them for one plugin, open that plugin in the viewer and switch off Show “View Docs” link on the Plugins page in the sidebar. The change is saved at once and removes all three links for that plugin. The setting exists only for plugins, since themes and must-use plugins have no row on the Plugins screen. Only administrators see and change it.
The links are shown only to users who can open the viewer, and only on the site's own Plugins screen, not in the network admin.