c0dx: WP Longread Navigator

Русская версия

A lightweight WordPress plugin for controlled navigation in long articles, guides, case studies and other long-form content.

Current plugin version: 1.1.1.

The plugin does not automatically collect every h2/h3/h4 heading. Navigation is built only from elements explicitly marked by the author through HTML, Gutenberg, TinyMCE or shortcode. This keeps the navigation structure under editorial control.

Project status

Version 1.1.1 is a stable working baseline used on a live WordPress site. Existing settings, post metadata, anchor navigation and frontend behavior were preserved during an in-place update from the earlier working version.

Further features and interface changes are planned only when they are justified by practical use and testing.

Features

• Manual navigation points through class="c0dx-wln-point".
• Optional short labels through data-nav-title.
• Stable generated anchor IDs with -2, -3 and further suffixes.
• Repeated manual IDs are reported and excluded after their first occurrence without rewriting the source markup.
• Gutenberg integration limited to enabled post types.
• TinyMCE integration for the Classic Editor.
• Shortcodes for navigation points and manual panel output.
• PHP, JS and Auto source modes.
• Desktop and mobile display modes.
• Active-section highlighting, smooth scrolling and aria-current="location".
• Fixed-header scroll offsets.
• Per-post settings and diagnostics.
• Top-level admin menu and Plugins-screen Settings link.
• Admin CSS loaded only on the plugin settings and supported editor screens.
• Clean uninstall of the plugin option and post metadata.
• No jQuery, Composer, npm packages, external services or custom database tables.

Compatibility

• WordPress 6.0+
• PHP 7.4+
• MySQL according to the installed WordPress requirements
• Vanilla JavaScript

Tested environment

The current baseline has been manually tested on:

• WordPress 7.0
• PHP 8.4
• MySQL 5.7
• a live long-form article using manual anchors and frontend active-section highlighting

Other supported WordPress, PHP and database versions may work but have not all been tested in every editor and display mode.

Installation

Installable release ZIP

Use the c0dx-wp-longread-navigator.zip asset attached to a GitHub Release when one is available. GitHub's automatically generated Source code archives are repository snapshots and contain the plugin inside a nested directory, so they are not intended to be uploaded directly through the WordPress plugin installer.

Manual installation from the repository

1. Copy the c0dx-wp-longread-navigator directory to /wp-content/plugins/.
2. Activate c0dx: WP Longread Navigator.
3. Open c0dx Longread Nav in the main admin menu, or use Settings on the Plugins screen.
4. Configure post types, source mode, display mode and appearance.
5. Enable navigation in the target post or page metabox.
6. Mark the required navigation points.

Basic markup

<h2 id="geo-aeo-basics" class="c0dx-wln-point" data-nav-title="What is GEO/AEO">
  What is GEO/AEO and how it differs from ordinary SEO
</h2>

If id is omitted, the plugin creates one automatically. Repeated generated slugs receive -2, -3 and further suffixes.

When the same manual id is used more than once, only the first navigation point is included. Later occurrences remain unchanged in the page markup and are listed in the post diagnostics.

Shortcodes

Navigation point:

[c0dx_wln_point id="geo-aeo-basics" title="What is GEO/AEO" level="1" tag="h2"]What is GEO/AEO and how it differs from SEO[/c0dx_wln_point]

Manual panel output:

[c0dx_wln_nav]

Documentation

• English documentation
• Russian documentation
• Changelog

Reporting issues and contributing

Bug reports and focused improvement proposals are welcome through GitHub Issues. A useful report should include:

• WordPress and PHP versions;
• editor or page builder;
• selected source and display modes;
• a minimal markup or shortcode example;
• the expected and actual behavior;
• relevant browser-console or PHP log messages with secrets removed.

See CONTRIBUTING.md before preparing a pull request.

Security

Do not publish credentials, tokens, private URLs, customer data or complete production logs in issues. See SECURITY.md for the reporting policy.

Repository layout

README.md
README.ru.md
LICENSE
CHANGELOG.md
CONTRIBUTING.md
SECURITY.md
.gitattributes
.gitignore
.github/
  ISSUE_TEMPLATE/
  PULL_REQUEST_TEMPLATE.md
c0dx-wp-longread-navigator/
  c0dx-wp-longread-navigator.php
  uninstall.php
  readme.txt
  assets/
  docs/

Installable ZIP archives are release artifacts and are not stored in the source tree.

License

MIT. See LICENSE.