Change log#

0.11.0 (2026-09-04)#

Backwards-incompatible changes#

  • The Highwire date tag is now citation_publication_date instead of citation_date. This is the name documented in Google Scholar’s inclusion guidelines, and it matches the tag Documenteer emits for user guides. Google Scholar and Zotero accept both names, so indexing is unaffected; only tooling that looks for citation_date by name needs updating. The value format (YYYY/MM/DD, in UTC) is unchanged.

New features#

  • New [technote.lint] table in technote.toml. Its ignore array lists the codes of lint rules to skip for this technote, for tools such as Documenteer’s technote lint command:

    [technote.lint]
ignore = ["TN105"]

    Technote doesn’t run lint rules itself; it owns the table so that every tool reads the same configuration. Codes are validated only for shape: an uppercase prefix naming the rule set, followed by a number (such as TN105 or R101). The table is available to Python code as TechnoteTable.lint (a LintTable model).

  • When technote.toml doesn’t set a title, the title from the document’s H1 heading is now resolved at the end of Sphinx’s read phase, in the env-updated event, rather than only in the HTML builder’s html-page-context event. TechnoteMetadata.title is therefore correct for every builder (such as dummy and linkcheck) and for tools that run a Sphinx read in-process to inspect a technote’s metadata. A title in technote.toml still takes precedence, and HTML output is unchanged. The rule is also available as a new function, technote.ext.metadata.resolve_title(), which returns a document’s H1 title from its doctree.

0.10.0 (2026-08-24)#

New features#

  • The [technote] doi field in technote.toml is now wired into the technote’s metadata. Previously this field was parsed but never reached TechnoteMetadata.citation, so the citation_doi Highwire tag was never emitted. A technote with a DOI now publishes it in its HTML metadata, making the technote’s page a proper DOI landing page.

    As well, the validation rules for doi in technote.toml is more flexible. The DOI can be written either bare (10.5281/zenodo.10385500), as a https://doi.org URL, or with a doi: prefix. It’s normalized to the bare form. A value that isn’t a syntactically-valid DOI is now a configuration error rather than being silently accepted. An empty string (doi = "") is treated as an unset DOI, so existing placeholder values keep working. An unquoted value (such as doi = 10.5281, which TOML parses as a number) is reported as a configuration error naming the doi field, rather than raising a traceback.

  • New Dublin Core metadata tags in the HTML head: DC.title, DC.creator, DC.description, DC.identifier, DC.date, DC.publisher, DC.type, DC.format, DC.language, and DC.rights. DC.identifier is the technote’s DOI when one is configured, and the canonical URL otherwise. These are generated by the new technote.templating.dublincore.DublinCoreMetadata class.

  • New schema.org JSON-LD metadata in the HTML head, describing the technote as a schema.org Report. When the technote has a DOI, the DOI URL is the node’s @id and the DOI is also expressed as a PropertyValue identifier, following the DataCite-to-schema.org crosswalk. This is generated by the new technote.templating.schemaorg.SchemaDotOrgMetadata class.

  • The [technote] organization field is now carried into TechnoteMetadata.organization, where it’s published as the DC.publisher tag and the schema.org publisher property.

  • New attributes on TechnoteJinjaContext for use in themes: citation, doi (the bare DOI), doi_url (the https://doi.org URL), dublincore_metadata_tags, and schemaorg_metadata_tags. Citation also gained a doi_url property.

Bug fixes#

  • A technote without a canonical_url in technote.toml no longer emits <link rel="canonical" href="None"> in its HTML head. The TechnoteJinjaContext.canonical_url property stringified the unset value into the literal "None", which search engines resolved as a relative URL to /None. The property now returns None, and the theme omits the canonical link entirely.

  • Content in meta tags is now HTML-escaped, so titles and abstracts containing ", <, >, or & no longer produce broken markup.

  • The citation_title Highwire tag now carries the data-highwire="true" attribute, matching every other Highwire tag technote emits.

  • The citation_author_institution Highwire tag is no longer emitted with empty content when an author’s affiliation is identified only by its ror (or internal_id). Previously such an affiliation produced content="", which indexers like Google Scholar read as an empty institution.

Other changes#

  • The SPDX license database is now loaded once per process rather than on each lookup.

0.9.1 (2025-07-25)#

Bug fixes#

  • Fixed the ROR URL validation regex to correctly match valid ROR identifiers.

Other changes#

  • Updated how license metadata is specified in pyproject.toml.

0.9.0 (2024-07-11)#

Backwards-incompatible changes#

  • We’ve “vendored” sphinx-basic-ng into the Technote project itself. This is to prepare for changing the technote theme to a two column layout.

  • Technote no longer uses the sphinx-basic-ng theme. Users that depended in the sphinx-basic-ng themes HTML and class structure for theming will need to update their CSS.

New features#

  • Technote now features a two-column layout. The left column contains the table of contents and metadata, while the right column contains the content. This layout allows for wide content to “bleed” into the whitespace to the right of the content column. With this change, we’ve dropped the CSS patterns from the sphinx-basic-ng theme. The Technote layout is now built around CSS grid.

  • Wide content (such as figures, tables, and code blocks) can now extend past the content column if the author sets the technote-wide-content class on the content. This class is applied as a figclass option in figures or as a preceding rst-class directive to tables and code blocks.

Other changes#

  • Adopt ruff for formatting (dropping Black).

0.8.0 (2024-05-02)#

New features#

  • Changed how the base font size is set. The base font size on the html element is now 100% to explicitly respect the user’s settings. The rem unit is now relative to those user settings as well.

  • The “default” font size is now set on the body element with the --tn-component-text-font-size CSS property. This is set to 1.1rem by default to maintain the original look. The header sizes are now relative to the user font size, but the smaller sizes have been increased slightly.

  • The font size for code is now set to 0.9em. This slightly smaller size helps avoid a baseline misalignment issue for the monospace text in the paragraph.

  • The pre font size is 1rem, which is slightly smaller than the text font size.

  • New --tn-component-code-font-family CSS property. This is used for monospace fonts in code blocks and inline code. The default is ui-monospace, which gives SF Mono on macOS.

Other changes#

  • Pin pytest < 8.0 due to a change in test sessions that’s incompatible with running a technote Sphinx build repeatedly on different projects. This change is temporary until we update the project builder for tests to run in subprocesses for isolation.

0.7.0 (2024-01-30)#

New features#

  • When the technote.date_updated field in technote.toml is not set, the update date internally defaults to “now” (the build time). This ensures that documents always carry some form of metadata about when they were modified.

  • Code samples without captions (unwrapped .highlight divs) now have borders and are protected against x-overflow. This matches the behavior of code samples with captions.

  • All code samples have negative left margin equal to their content padding so that the code lines up with the text column.

  • The content (div.sb-container) now has bottom margin to give content breathing room.

0.6.2 (2023-12-14)#

Bug fixes#

  • Fix the technote.ext.pygmentsscss extension to handle cases where the HTML builder isn’t being run.

0.6.1 (2023-12-14)#

Bug fixes#

  • The technote.ext.wraptables and technote.ext.insertposttitles extensions now gracefully handle cases when an index.html file does not exist. A reason for this might be that the build is running through the linkcheck builder.

0.6.0 (2023-12-05)#

New features#

  • Add #svg-octicon-versions-16 to the octicons.html sprite template. This icon is useful for linking to alternative versions of a technote.

  • Add #svg-octicon-mortar-board-16 to the octicons.html sprite template. This icon is useful for linking to the document’s citation.

  • Export a variable, T from technote.sphinxconf that is an instance of technote.main.TechnoteSphinxConfig. This is useful for organizations that need to access the technote configuration and metadata in their own technote theme.

  • Figures and tables with captions are now numbered using the Sphinx numfig configuration. Authors can reference figures by number using the numref role pointing to the figure’s name option.

  • Authors are now listed below the title of the technote. This is a change from the previous behavior of listing authors in the sidebar.

Bug fixes#

  • Fix the sidebar-authors.html component template so that extra spaces aren’t introduced between authors and commas.

0.5.1 (2023-11-29)#

Bug fixes#

  • Add sphinx.ext.intersphinx to the extensions list in technote.sphinxconf. This extension is required to use the [technote.sphinx.intersphinx] configuration.

0.5.0 (2023-11-28)#

Backwards-incompatible changes#

  • New structure for the PersonName model (used for the name key in [[technote.authors]]):

    • Delete the name key to require structured names

    • Rename the given_names and family_names keys to given and family, respectively, which works better in context.

New features#

  • Add a new organization key to the [technote] table to capture information about the organization publishing the technote series.

Bug fixes#

  • The edit-on-GitHub link created in the Jinja context now correctly points to index.md if appropriate. Previously it assumed that the source page would be index.rst.

  • Allow the date_created`` and date_createdkeys in the[technote]table to use native TOML date formats (e.g.,2023-11-20T14:40:22Z`, without quoting as a string).

0.4.0 (2023-10-31)#

New features#

  • Added the myst-parser to the technote extension set. This allows Markdown files to be included in the technote build.

Bug fixes#

  • Images added with a plain .. image:: directive are now constrained to a maximum size of the container width. This is the same behavior as figures.

0.3.0 (2023-10-26)#

Backwards-incompatible changes#

  • Require Pydantic 2 and later

  • Require Python 3.11 and later

  • The technote.status field is changed. The “planning” and “active” states are now “draft.” The values in the supersceding_urls array are now tables with url and title (optional) keys.

  • The metadata for creation and update dates are now maintained as full datetime objects rather than date objects.

  • Refactor the original technote.config module into separate modules and classes for modeling technote.toml settings, internal representation of metadata (technote.metadata.model.TechnoteMetadata), the front-end for bootstrapping the Sphinx configuration in conf.py (technote.main.TechnoteSphinxConfig), and the Jinja context for HTML templating (technote.templating.context.TechnoteJinjaContext). A new factory class is responsible for creating these objects (technote.factory.TechnoteFactory). The benefit of this architecture is that it’s not possible to continue building metadata from additional sources (external APIs and the technote context) since the metadata is not longer strictly tied to the technote.toml file representation.

New features#

  • Light and dark colour themes are now set via a html[data-theme='light'] or dark data theme attribute. JavaScript sets this element based on the user preference of ‘light’, ‘dark’, or ‘auto’ (using media queries for system settings). New CSS classes technote-themed-light and technote-themed-dark now determine what elements appear, or not, in certain themed contexts. This mechanism is highly inspired by pydata-sphinx-theme.

  • Pygments highlighting CSS is now applied to all code samples, with light and dark themes using the mechanism described above. The default pygments styling comes from the accessible-pygments package. The mechanism for setting a light and dark Pygments theme is also based on pydata-sphinx-theme.

  • New CSS custom properties for setting light and dark responsive colours.

  • Include common metadata in the technote HTML:

    • Standard HTML meta tags like description and canonical URL link rel.

    • Highwire Press meta tags (used by Google Scholar)

    • OpenGraph meta tags (used by social media and messaging apps)

    • microformats2 annotations on relevant elements

    • Custom data attributes on relevant elements (the link to the technote source repository)

  • Improve styling of the local table of contents. The outline is now sticky to the document and is independently scrollable if longer than the viewport.

  • The content in the primary (left) sidebar is also sticky to the document and is independently scrollable if longer than the viewport.

  • Improved styling:

    • Style the permalink icon

    • Style code blocks

    • Style admonitions

    • Style the metadata in the sidebars

    • Style footnotes

    • Style citations

    • Style quotes

    • Style tables and add a wraptables`` Sphinx extension (included with the technote extension set) that wraps table elements in a figure` to ensure wide tables have horizontal scrollbars

    • Improve layout in the mobile view

  • The new “insertstatus” Sphinx extension, included in the technote.ext Sphinx extension, inserts an aside element below the title of the technote describing the status. The status is only published for non-stable states.

  • Ignore common infrastructure directories and files from the Sphinx build.

Bug fixes#

  • The technote.ext.toc extension now correctly handles the case where a technote has no sections.

Other changes#

  • Adopt Ruff for linting

0.2.0 (2022-12-05)#

This version adds customized Jinja templates as well as CSS to implement the core technote reading experience on the web. This version includes an abstract reStructuredText directive, as well as a customized table of contents context variable for Jinja (technote_toc).

0.1.0 (2022-10-21)#

First release of technote.

This page was last modified on .