A.N.R.GHG Publishing Toolkit

The dots have been added to help screenreaders spell it as an initialism rather than as an acronym.

The climate crisis requires us to enroll all aspects of our work and lives so that our efforts converge towards addressing the crisis now as a top priority urgency.

The AMP technology contributes to streamlining processes and making the internet less energy-consuming.

Moreover, development and maintenance are powered with renewable energy as well since the developer subscribed to the green electricity option offered by the local grid operator to individual households at a monthly fee of about $2.

Most importantly, the developer is a vegetalian, as avoiding meat and dairy, eggs and fish helps making an end of animal torture and is the scientifically recommended single biggest way to reduce our impact on planet Earth, an Oxford University study assessed.
Why are multiple features crammed into a single plugin?
A number of features like heading links and table of contents, notes and sources or last modified date and published date of pages are interrelated, and solutions using one plugin per feature are suboptimal because of inconsistent identifiers or presentation.

Beyond consistency, among the reasons that further fueled the adoption of an “all”-in-one concept are efficiency and economies of scale, much like what Jetpack is achieving at an incomparable magnitude.

As a result, making individual plugins out of some of the features is not required and would be inefficient. Keeping them all together seems like the best option.
Why are all settings crammed together on a single page?
This way, the settings can be searched using the browser search functionality (Control + F), and all occurrences can be accessed directly. That would not be the case if the settings were grouped by topic under a number of tabs.

The table of contents at the top of the settings page replaces the tab row or column, while allowing for longer, more explicit labels. It can be accessed by clicking the ‘Back to top’ button at the top of the window in a fixed position.

Likewise, the ‘Save settings’ button is constantly visible at the bottom of the window. Clicking it does not require scrolling down to the bottom of the page.
Why do processes fail when this plugin is active?
This issue depends on the PHP memory limit. The large settings page requires more than 32MB. Safe is to set the PHP memory limit to 256M as a rule of thumb, but many hosting providers throttle it down to 128M. If your plan includes cPanel, more options such as 512M may be available in the “MultiPHP INI Editor” under “Software” in the “Tools” menu on the cPanel home page in your hosting account.

The limitations involved by a low memory limit affect plugin updates, theme updates, as well as other actions performed by WordPress and its plugins, for example editing large posts in the Block Editor. Other content management systems are likewise impacted by low memory limits such as 32M, that may be the default settings value in shared hosting.
How about using jQuery?
As the jQuery JavaScript library is not fully AMP compatible, features like tooltips, expand/collapse and scrolling back and forth do not use jQuery. Another reason is that when using jQuery, and JavaScript is turned off in a browser, these features are broken in that browser. Yet another reason is bad user experience as links to end notes are either unavailable, or available hard links cannot be opened while the relevant list is collapsed. Moreover, using jQuery prevents from saving a fully functional copy of a page. These frustrating issues outweigh the benefits of using jQuery.

Regardless, for end notes there is another plugin out there that uses jQuery by default and offers the ability to opt out: The Footnotes plugin, although closed since 2022-11-14, was consistently recommended in 2023, and it is compatible with the Twenty Twenty-Three theme. It can be installed as a .zip file following process B after downloading its latest version directly from the WordPress Plugin Directory, as it is one or two times a day on average per current stats, or from the latest backup of its full Plugin Directory page in the Web Archive.

However, since the Footnotes plugin is unmaintained, it may basically become a target of exploiting security vulnerabilities. That is why reading the abandonment statement made by its last developer, or its archived version, is strongly recommended.
Can I use various themes alongside?
Yes, using configuration filters, that have precedence over settings values from the database, each theme can have specific settings values stored in its child theme’s functions.php, so that sensitive values may be fine-tuned in accordance with particular layout options, while values that are constant across themes may still be configured in the settings page and called from the database.

The A.N.R.GHG Publishing Toolkit includes a template file called template-filter-config.php documenting all filters available so far (while process filters are being added as documented in template-filter-output.php).
How to keep configuration filters when switching themes?
As a stable place to add configuration filters and process filters, a mini plugin is convenient. A mini plugin template is included in the plugin folder. To use it, please move it out of the folder, eventually rename it, optionally place it in a new folder, then make it a plugin by deleting the seven percent signs standing out in front of the %%%%%%%Plugin Name: field label, and activate it after refreshing the Plugins list.
Why are the strings not in the translation pane?
For multilingual plugins to show the strings in the translation pane and to work effectively, the translation keys must be present in the database. To achieve this, please access the plugin’s settings page and click the ‘Save Settings’ button at the bottom of the window.

After this, all translatable configuration values will show up in the translation pane, even those that are not yet configurable on the settings page.
Are rich-text category pages supported?
Yes, category pages are supported through the term_description hook, so that all features are fully functional as configured.

When using the A.N.R.GHG Publishing Toolkit, category pages are unaffected by the filter that would usually delete HTML markup, and may be drafted like pages in the Block Editor, kept as drafts, and copy-pasted from the Code Editor to the term description window. Eventual leftover block markup is removed at runtime.
Are custom post types supported?
Yes, the A.N.R.GHG Publishing Toolkit supports all post types applying the filters hooked on the the_content hook; for example, custom post types of WooCommerce like product pages are supported through this hook. Additionally it supports popups from Popup Maker (Code Atlantic) by hooking on pum_popup_content, and from Popup Builder (Sygnoos) by hooking on sgpbSubscriptionForm.

Beyond, it processes a configurable list of additional hooks. The only requirement for a content type is to apply filters on the content, using whatever hook. The name of that hook needs to be filled in an input field on the settings page, or in the configuration filter found among the templates under “Support alternative content hooks.” Multiple hook names are comma-separated.

For convenience, a dedicated hook is also available, that the A.N.R.GHG Publishing Toolkit adds filters to for subsequent application to a given content by calling the WordPress apply_filters() function:

$content = apply_filters( 'anrghg_content_filter_hook', $content );

Are custom fields supported?
Wysiwyg fields added using Advanced Custom Fields are optionally processed for inline complements and other features as well, and complement lists are appended at the bottom of each field. That can be deactivated so that these fields would be processed as part of the post content if displayed accordingly.

Alternatively, when the hook that the field applies filters to is known, its name may be added to the content hooks in the settings.

The A.N.R.GHG Publishing Toolkit also adds numerous fields, among which the ‘first published date’ that will be displayed if its prefill has been changed in the Post Meta box.
Can I use shortcodes instead of blocks?
Yes, sort of. The A.N.R.GHG Publishing Toolkit does not rely on the WordPress Shortcodes API, because Shortcodes cannot be used to reliably process notes and sources. For example, the scheme is disabled in forms set up using the WPForms plugin. Also, available options are too restricted and may exclude your preferred ones; so, not being internationalized, the shortcode API fails on Non-Latin shortcodes; and not being versatile, it cannot process delimiters made of brackets, braces, parentheses or other punctuation characters only.

Additionally, registered shortcodes are removed from other usages such as schema and meta descriptions for SEO. That is appropriate for most shortcodes, but may not be desirable for sources: Stripping off these complements may convey a misconception of the content as containing unsourced statements, and thus harm the website’s reputation.

On the other hand, the A.N.R.GHG Publishing Toolkit is fully compatible with the Classic Editor relying on shortcodes: Instead of using the blocks, fully configurable strings like [anrghg_toc] and [/anrghg_section] may be manually inserted, both with optional arguments.
Can the appended message be edited in rich text?
Yes, by configuring it in the Template editor. Then insert its name in the input field on the settings page or as a return value in the configuration filter.
Can I use the post title in the appended message?
Yes, to insert the title of the current post or page, please insert the placeholder %s in the template text.
Why does the link to a code block not show up on hovering the code?
As the code block is scrollable, its overflow is hidden, so any protruding elements like the paragraph link are cut off. To work around the issue, code blocks are wrapped into a paragraph, but this paragraph becomes two paragraphs due to the block level code block, and the first paragraph stops before the code. That is why the link shows up only when hovering the area in the margin before the start of the code.
Does adding a paragraph break links to other paragraphs?
In most cases not, because the identifiers that the A.N.R.GHG Publishing Toolkit assigns are content-based, both for Latin and for non-Latin scripts. These are URL-encoded, much like WordPress derives slugs from titles.

The main case where numbering is added is to disambiguate identical headings.

As paragraphs are unlikely to have identical beginnings spanning over more than 200 characters—the length that fragment identifiers are shortened to before cleaning up truncated last words—, every paragraph has a unique stable identifier, unless the underlying text is modified, resulting in the need to fix the fragment identifier.

HTML anchors set in the WordPress block inspector’s “Advanced” section have precedence over content-derived anchors. Like these, they are prepended with the post number. The part after this and the separator may be copy-pasted into that field to make an existing paragraph link insensitive to further edits, provided that the resulting discrepancy is not an issue.
How to edit headings or paragraph starts without breaking links?
By giving them an “HTML anchor” in the Block Inspector. For each heading, paragraph or list item, the A.N.R.GHG Publishing Toolkit uses its existing “HTML anchor” in the first place. Only if none is configured, it proceeds to derive a fragment identifier from the content.

If a URL with a content-based fragment ID is in use prior to editing the underlying content, then the existing ID may be grabbed in preview mode and copy-pasted into the “HTML anchor” input field without the prepended post ID, as this number is always prepended automatically to any ID.

Prepending the post number helps ensure that each ID is unique across the website, in support of the infinite scroll (AJAX autoload) feature.
How to position the table of contents without the block?
That is done by typing [anrghg_toc] or any bracketed string that this code is configured to.

Arguments between the code name and the closing bracket are also supported, and both names and values are designed for ease of input. Argument names are preceded by a space and start with an underscore. Values are delimited by vertical bars. The equals sign may or may not be space-padded:

Label tailored to the instance: _1=|Contents of ‘%s’|, where %s is replaced with the post title (for tables after the post);
Alignment: _2=|0| or _2=|center|, or _2=|-1| or |left|, or _2=|1| or |right|;
Collapsing behavior:_3=|-1|for expanded (and collapsible), or_3=|1|for collapsed (and expandable), or_3=|0|` for uncollapsible.

Why are level 1 headings supported?
Stray level 1 headings do indeed have a negative impact on search engine rankings. Using H1 outside the post title is strongly discouraged. Also the heading formatting defaults to H2 in the Block Editor, while in the Classic Editor the shortcut Shift + Alt + 1 is deactivated. We are warned.

Yet multiple level 1 headings are in current use outside the web, so the support for H1 is consistent with standard word processing user experience. And when the .docx or .odt formats are converted to WordPress, headings are usually not downgraded (despite they should be), to prevent H6 from being degraded to paragraph level, since custom H7 markup is not well supported by the web.

The A.N.R.GHG Publishing Toolkit supports level 1 headings if they are present in an article body, because H1 formatting is available in WordPress, that inherits it from TinyMCE where it makes actual sense, as TinyMCE is also used in systems that may not feature an extra field for the page title.
Do the added fragment IDs interfere with my custom anchors?
No, because the “HTML anchor” configured in the Block Inspector is added right inside the element’s start tag, while the A.N.R.GHG Publishing Toolkit adds its IDs in an extra span.
Can I have heading anchors also in a linked PDF?
Yes if they are built-in; but these fragment identifiers are like scroll instructions. More universally, using URL parameters, scroll instructions may apply to any PDF opened in a browser:

To scroll to the page, add a hash to the PDF’s file name in the URL, then page= and the page number:

To scroll to a heading in the page, append an ampersand, then zoom= and three comma-separated numbers: first the zoom factor in per cent (a zero is interpreted as 100%), next the X offset in pixels, then the Y offset. Basically you only need the third number, a best-guess determined by trial-and-error or measuring pixels so that the target heading displays a little below the upper viewport edge:

How is the table of contents expanded?
The A.N.R.GHG Publishing Toolkit’s table of contents features a CSS-only transition when expanding or collapsing.

For AMP compatibility, JavaScript is avoided on public pages when the same behavior is not implementable in the AMP framework.
What is the lone heading after the table of contents label?
That happens after clicking a heading number while JavaScript is turned off, because expanding the table of contents from heading numbers relies on JavaScript (either in AMP or Vanilla); else, the scrolling wouldn’t work. So, without JavaScript, the target list item displays alone thanks to CSS, and the table of contents waits for its label or twistie being clicked to expand by CSS.

There is a small likelihood for the same to happen while JavaScript is on. On AMP pages, the related style rule is always valid, but after clicking a heading number (which is when it would come into play) it is overridden by another one, activated using the AMP framework. Reloading the page in that state would result in a lone heading as pointed in the question.
How are complement lists expanded?
The A.N.R.GHG Publishing Toolkit’s complement lists are expanding or collapsing by CSS only, with a slight transition.

For AMP compatibility, JavaScript is avoided on public pages when the same behavior is not implementable in the AMP framework.
Why are complements not soft-linked?
Compared to hard links, soft links have multiple downsides, while the disadvantage of using hard links is easily mitigated by hitting the backbutton instead of clicking backlinks. A configurable plain tooltip on hovering a backlink suggests this workaround, that will remove the anchor click from the browsing history.

Moreover, hard links allow accessing complements from outside, as they are the precondition of using the :target CSS selector to display the desired complement only, without expanding the whole list. That scheme always helps your visitors not be distracted from the other features and contents often displayed after or before the complement lists, notably the social icons and related posts. Your visitors may see these features as soon as looking up a complement in the list, as an alternative to checking it out in its tooltip.

Thanks to using hard links, no script is used, and since expanding and collapsing complement lists and tables of contents from their label is done without JavaScript likewise, the A.N.R.GHG Publishing Toolkit’s features are fully functional in browsers where JavaScript is turned off (and AMP actions won’t work either). Additionally, for convenience, CSS-based scroll offset as well as smooth scrolling are supported, too.
Are identical complements combined?
Yes, optionally identical notes or sources are combined into a single item with a single number. Thanks to using hard links, scrolling back up is performed by using the backbutton. For reference, all links to the instances where the complement is used are enumerated in a tooltip on hovering the complement number in the list.

Notes and sources are only combined section-wide. Identical complements occurring in several sections of a post or page appear once in every related list.
What are the numbering options for notes and sources?
Beside the standard Western Arabic digits, notes and sources may be numbered using Eastern Arabic digits, or be numbered each in a distinctive manner among Roman and Latin numerals, both available in lowercase and uppercase.
Are long complements truncated for display in tooltips?
Never, because the tooltips are styled in a way that truncating is unnecessary. When exceeding a configurable number of characters, the tooltip displays full-width even on desktops, and if it would exceed a configurable maximum height, it becomes scrollable.

That said, the A.N.R.GHG Publishing Toolkit supports a dedicated tooltip text, similar to WordPress’ manual excerpt feature. If the (configurable) [/view] delimiter is present in the complement, the text before is displayed as tooltip text, while the following text represents the complement in the list. This is linked to from the end of the tooltip, and from anywhere in the tooltip by delimiting the link text with [link] and [/link], or any delimiters these are configured to.
Can complements be nested?
Yes, provided that the nested ones are sources, and those they are nested in are notes. Notes cannot be nested in sources, nor notes in notes, nor sources in sources. Only this nesting scheme is supported, but each note may include any number of nested sources:

…[note]…[src]…[/src]…[/note]

Can I start using other delimiters from now on?
Yes, there is an option to configure the current delimiters separately along with the ID of the post where the new set of delimiters is used first. Currently this requires using configuration filters. Once that is done, new delimiters may be configured the usual way without affecting the older posts and pages.
Can I delimit sections for complements without using the block?
Yes, by ending the section with [anrghg_section] or any bracketed string that this code is configured to.

Arguments between the code name and the closing bracket are also supported, and both names and values are designed for ease of input. Argument names are preceded by a space and start with an underscore. Values are delimited by vertical bars. The equals sign may or may not be space-padded:

List labels tailored to the instance: _11=|Notes of ‘%s’| and _12=|Our sources|, where %s is replaced with the post title;
Writing direction tailored to the instance: _21=|-1| in Note list, _22=|-1| in Source list, or _20=|-1| in both lists, where -1 is right-to-left, and 1 is left-to-right;
Collapsing behavior tailored to the instance: _31=|-1| for the Note list, _32=|-1| for the Source list, or _30=|-1| for both lists, where-1is expanded (and collapsible),1is collapsed (and expandable), and0` is uncollapsible;
Footer deferral: _40=|1| or _40=|0| for whether this instance must be deferred to the footer, or must not be deferred.

Could multipage posts display all notes at the end?
Multipage posts are reported not to be properly indexed, and they are not properly navigatable either, with page numbers at the bottom only, and no distinctive head zone for the extra pages. Thus, ‘Page break’ is a bogus feature and should never be used.

Being able to read the whole content merely by scrolling is much more user friendly. Consistently, implementing anything specifically for multipage posts would be wasting the time of all involved parties, which is why WordPress did not properly implement its multipage feature in the first place.
How to reset the settings to default values?
The easiest way is to import an empty file.

Alternatively, deleting the ‘anrghg’ row in the ‘wp-options’ table in the database has the same outcome.
Why do setting descriptions not display in tooltips only?
Info hover buttons would cause issues for either accessibility or keyboard navigation.

Thanks to the ‘Save settings’ button being constantly visible at the bottom of the window, the settings are not spatially constrained. If full tab navigation is active, the ‘Save settings’ button is active after each settings section.

Although the settings page is mostly visited at setup while information is wanted, but less often later on, the settings page verbosity is configurable at three levels, one of which is with information expand buttons. Another option fully hides almost all explanatory information.
Why is the database so heavy?
That is mainly due to WordPress documenting by default the full version history of every post and page.

If this is too much information and ends up taking too much disk space, with backups getting bulky, and potentially restoring the database would be hard, then revisions may be deactivated by defining the constant WP_POST_REVISIONS as false.

Another option is to limit the number of stored revisions as in the example provided in the file template-wp-config.php.