Skip to content

Latest commit

 

History

History
730 lines (450 loc) · 22.3 KB

CHANGELOG.adoc

File metadata and controls

730 lines (450 loc) · 22.3 KB
Raw

Changelog

2.1.11

Support for extra_footer_links site configuration option. Links can be provided in the format:

extra_footer_links:
  - { url: "/about/", title: "About ELF" }

They are shown in footer alongside spec and software index links.

2.1.7

Support added for customizable branch names.

The implied default is main.

Any setting that accepts a Git repository URL, which are named following the *_repo_url convention (git_repo_url, repo_url, or github_repo_url), accepts a sibling setting *_repo_branch which will override the implied default and site-wide default_repo_branch value.

Important
Breaking change

The default branch name is now main, which is a departure from the previously hard-coded master.

Quick migration guide:

  • If your site references (using *_repo properties) repositories that use other main branch name than main, locate those references in .adoc YAML frontmatter and add sibling properties in the shape of *_repo_branch (basically, adding _branch suffix), assigning the actual branch name used in each circumstance.

  • If your sites all use another branch name than main, you can edit all sites’ _config.yml files and specify your custom branch name using default_repo_branch property. (If you opt to use this way of configuration, and you unite multiple open project sites under a single hub site, you must make sure default_repo_branch property in _config.yml files is the same across all sites, as well as the hub site. If that’s impossible, please use the previous option.)

If you experience site build failures after the update, the error that looks something like below would indicate that the build fails due to branch name issue:

in `command': git
'--git-dir=/site/path/some/repository/path/.git'
<...part removed for clarity>
pathspec 'origin/some_branch_name' did not match any file(s) known to git
(Git::GitExecuteError)

In the above example, project site is trying to fetch a repository (e.g., for software documentation) using some_branch_name as the main branch, while that repository in fact uses a different one. You can use /site/path/some/repository/path to locate the relevant .adoc (or .md) file with frontmatter YAML and override branch name there.

2.1.0

Bumped Jekyll dependency to 4.0.

2.0.22

Fixed an issue where excerpts for posts written in AsciiDoc could break landing page blog roll layout, if those excerpts happened to contain certain formatting.

2.0.20

  • Fix compatibility with jekyll-data gem (@ronaldtse)

2.0.19

External link marking functionality was split out of the helpers gem into jekyll-external-links plugin.

Correct CTA button appearance on landing page.

2.0.18

Fixed an issue where project hub site can fail to build when some project blog post contents contain a string that interprets as invalid Liquid markup.

2.0.17

Important
Breaking change

Blog post permalinks were changed to be in the form of YYYY-MM-DD-<post title>.

It’s recommended to specify redirects for posts (using jekyll-redirect-from plugin and redirect_from frontmatter key). For example, this would ensure that a blog post named 2025-12-31-hello-world.adoc will still work under the pre-2.0.17 URL scheme, redirecting to the new path:

redirect_from:
  - /blog/12-31-2025/hello-world/

  • Fixed inappropriate scrolling of admonition blocks that could manifest itself on narrow viewports in some circumstances.

  • Prevented documentation navigation sidebar from clipping on narrow viewports when some navigation items are too long.

2.0.16

Made it possible to specify multiple post authors via authors YAML frontmatter key. Each author object in array uses the same structure as the original author key, and singular author is still supported.

Fixed an issue where JS initialization could fail if Algolia search script didn’t load.

2.0.15

Code listings now include copy button. Copy button can be hidden by prepending code listing with a [.nocopy].

2.0.14

Added “suggest edits” and “toggle ToC” buttons to all project site documentation pages.

Fixed an issue where on some software documentation pages the “suggest edits” button would not have correct URL to Github edit page.

Improve robustness of external link detection.

2.0.13

Fixed an issue with item card layout on project site software/spec index pages.

2.0.12

Fixed an issue where extraneous items were included in software/spec indexes on open project hub sites.

Slightly improved layout of software, spec and blog post cards across the sites.

Added software & spec index links in site footer.

2.0.11

Work around an issue where robots.txt and sitemap.xml output by jekyll-sitemap would contain wrapping HTML with old doctype, as if rendered with some layout, and would thus be treated as invalid.

2.0.10

Fixed an issue where overrided includes, placed in site root as required, were included in the output unnecessarily.

2.0.8/2.0.9

Corrected a couple of accessibility blunders.

2.0.7

Improved featured project card layout on hub site landing page, so that it is not cramped on insufficiently large viewports.

Improved & documented favicon/touch icon support.

2.0.5/2.0.6

Fixed an issue that could cause hub site to require a preliminary build in order to pull all the required data from project sites correctly.

2.0.4

Fixed an issue where screen width breakpoint differed in CSS media query & JS.

2.0.3

UI responsiveness: reduced “big screen” breakpoint to 800px wide viewports.

Fixed an issue with software/spec card layout on hub site index & landing pages.

Fixed an issue where parts of specification rendered on project site spec pages obscured navigation sidebar and expandable header menu on certain viewport widths.

2.0.2

Fixed the issue where icons did not work out of the box:

  • Ensured only free icons from Font Awesome 5 are used.

  • Added configuration option to disable default Font Awesome CDN if the user wants to supply a custom distribution (different version or different hosting/CDN).

Fixed a minor layout issue with item card headers on project landing page.

2.0.1

Fixed a couple of issues:

  • External link displayed on software / spec landing page were broken on narrower screens.

  • Featued items on landing did not get sorted correctly by specified priority.

2.0

Important
Breaking changes

  • Update software & spec entry point frontmatter according to new external link support (some YAML keys are now obsolete).

  • If you customize styling:

    • Rename SASS variable $superhero-background. Details below & in the styling customization part of theme’s README.

    • Beware of changes in project & hub site landing pages’ HTML markup structure.

    • Beware of minor styling refactoring across the board.

Software & specs external links overhaul (BREAKING)

Software and spec entry points now support external_links key in YAML frontmatter. External links are specified as one array of objects, each with a required url and an optional title property.

This is a more natural any to configure any third-party site links such as source repositories, documentation (for software), specification views (for specs).

Frontmatter keys previously used to achieve the same purpose are now obsolete:

  • Software’s docs_url

  • Spec’s ietf_datatracker_*, rfc_id, source_url

Note
 For software, now specifying the mandatory repo_url does not automatically result in source repository link being shown anymore. You must have repository URL in external_links if you want the link to appear. (This might seem as redundant, but it also allows to not hide the repository link if desired.)

Project site landing page overhaul (BREAKING)

In addition to purely looks (e.g., using full-height background), landing pages for project sites were made more convenient.

There was a change in design approach—from landing pages focused on one single call-to-action, to landing pages with more actions and higher information density.

Simplified landing page layout for single-software projects

If an open project consists of only one software package (which is somewhat typical), its site’s landing page will be simplified.

Customizable landing page section order

Introduced site-wide configuration key landing_priority.

Project sites can use it to change section order for the landing (home) page, and specify a custom intro include. For an example, see Metanorma and Cryptode sites in Ribose Open network.

More useful actions exposed

  • Visitors can now quickly jump into software’s documentation: if software has docs (and top-level navigation items are clickable), links to up to three first documentation sections are displayed.

  • Software & spec cards now show external links, allowing visitors to quickly download software or view specification on SDO site or elsewhere.

Miscellaneous UI updates & styling refactoring (BREAKING)

  • HTML structure on landing has simplified. If you rely on it for styling purposes in your sites’ style.scss, you may want to check that your styling rules keep working as intended.

  • SASS rules across the board were updated, and a couple variables changed names.

    • The $superhero-background variable is now called $main-background.

      • By default, it is now a gradient based on primary and accent colors.

    • $hero-background variable has been removed.

    • .item selector on <li> elements in navigation blocks is no longer used.

  • Removed “tagline” after main title from stock spec & software index pages hero include. It didn’t add much and required extra copywriting effort.

  • Removed redundant Home link in top site navigation.

  • Made sure that there is spacing between site content & viewport edge, which used to be uncomfortably tight on particular viewport widths around responsive media query breakpoints.

  • Footer layout was updated.

  • “Featured” indicator on software & spec cards no longer features a thumbs-up emoji.

  • Many smaller changes across the board.

Improved documentation page UX

When navigating to a path with an anchor (hash) in URL:

  • The anchor itself should not be obscured by site header anymore (the page will immediately scroll up a bit, readers shouldn’t notice that).

  • The link corresponding to appropriate section is highlighted in the navigation sidebar.

Page header and navigation sidebar were made a bit cleaner.

Bug fixes

  • Stopped adding external link marker & bottom border to certain links (e.g., OSS badges).

  • Fixed layout issue in top menu, which used to slightly break layout when very long.

  • On hub site software & spec indexes, fixed vertical alignment of project icon on item cards.

  • Relaxed constraint where spec build’s PNG diagrams engine required specific navigation.

1.3.3

A few updates to how some blocks in AsciiDoc-generated markup appear visually, including marking warning and important admonition block with colour.

1.3.2

A few updates to how some blocks in AsciiDoc-generated markup appear visually (admonition blocks, listing blocks and figure titles).

This means blog posts, documentation pages and other content authored in .adoc will appear neater.

1.3.1

  • Added “Further in this section” on project documentation pages, when navigation item corresponding to the currently open page has nested items

  • Improved issues with page layout on narrower screens

Adjusted typography in general and improved formatting of some AsciiDoc features, such as:

  • Source listings

  • Callout numbers (particularly in source listings)

  • Admonition blocks

1.3

  • Documentation on open project sites now adds navigation across in-page header hierarchy below currently selected item in the sidebar.

1.2.5

  • Now recognizing Facebook & LinkedIn social links (with appropriate icons)

  • Added more ways of specifying blog post author photo

  • Added support for navigation.base_url to simplify navigation configuration in docs frontmatter

  • Added support for title / article_header_title specified on layouts, in addition to concrete pages

Hid external icon markers appearing on social link icons & ruining blog post page appearance.

1.2.4

  • Enabled Algolia search on hub sites

  • Avoiding building spec contents on hub site build

1.2.3

  • In tag lists on software & spec cards, now showing full tag name in tooltip. Useful for longer tag names that get clipped due to card width

Continued work on documentation navigation:

  • Improved appearance of documentation home pages

  • In documentation navigation for software and specs, added an explicit link to item’s documentation home and made the navigation sidebar easier to toggle directly by clicking on item title

  • Better navigation sidebar shadow appearance on Firefox

  • Fixed a regression introduced by new navigation that broke specification page styling and caused PNG diagram pages to not display at all

  • Fixed software docs not displaying properly if their source location is different than docs/ subtree within the Git repository

1.2.2

Documentation navigation display improvements:

  • Make sure documentation pages work even if navigation structure is not specified

  • On narrower viewports, initialize navigation sidebar in collapsed state to avoid covering the content

1.2.1

A couple of bugfixes to new documentation navigation widget’s behavior.

1.2

This update features a major update to documentation UX.

  • Enabled project-wide documentation via docs-base layout (see Metanorma’s example), integrated with the same navigation UX as software docs

Major update to docs navigation UX:

  • Now an expandable side panel that can stay on screen while reading

  • Now reusable across other docs in addition to software docs

Bugfixes:

  • Blog entries are now sorted by timestamp descending, as expected

  • Items in a grid now are of consistent width even when last row contains fewer items

  • Fixed clipped “Featured” labels on software/spec cards on hub site

1.1.27

  • Fixed broken project navigation links

1.1.26

  • Added support for project-wide documentation in the same style as in software package docs

  • Improved documentation navigation UI (now header is shown while scrolling)

  • Fixed issue where software/spec item cards fail to maintain width depending on their contents

  • Fixed an issue where html-proofer gem recommended by CI_OPS docs caused build failure due to breaking change in a recent version

1.1.25

  • Added support for displaying specification contents as part of project sites. In this first iteration, only PNG diagrams as in Metanorma model specs are supported

  • Added support for new simpler way of configuring software/spec navigation through document frontmatter, rather than a separate navigation.adoc file (the latter approach is to be deprecated)

  • Fixed an issue where featured software cards on project site landing would not display namespaced tags correctly

  • Layout improvements & fixes

1.1.24

  • Improved tag filtering experience

  • Added support for tag namespaces

  • Fixed a bug where search widget would attempt to be initialized in absence of search input

1.1.23

  • Algolia search can now be easily enabled on project sites by adding a key to Jekyll’s _config.yml

  • Now linking software docs to corresponding GitHub’s edit pages, a shortcut to allow documentation readers suggest edits with less friction

  • Simplified deployment by bundling Rakefile and .travis.yml and documenting the corresponding GitHub → AWS S3 setup in CI_OPS

1.1.22

  • Fixed an issue with software documentation landing page layout not displaying correctly depending on viewport height & the amount of landing page contents (Firefox only)

  • Started marking external links within main site contents

1.1.21

  • Better styling support for AsciiDoc-rendered HTML in site contents

  • Added tag-based filtering for software & spec indexes on project sites

  • Fixed an issue where ordering of software by last modification timestamp was messed up when timestamp was not present on some packages

1.1.20

  • Fixed a regression introduced in previous version that caused cards from hub site software & spec indexes to not link to their pages on corresponding project sites, 404’ing instead.

1.1.19

Improved software and spec indexes on both hub and project sites:

  • Order software and specs by last update timestamp, descending

  • Highlight featured software and specs

  • Show featured software/specs first in corresponding index listing on project sites

1.1.18

Updated layout of landing pages for both project and hub sites.

  • Fixed issues with inelegant whitespace

  • Hero unit look updated overall, is now more compact

  • Now showing featured items as a grid

1.1.17

Fixed an issue with code listings not always being horizontally scrollable, in those cases causing layout of documentation pages to exceed screen width.

Added favicon to base page meta (sites are expected to provide /assets/favicon.png and /assets/webclip.png now).

Made top header collapse on scroll for better readability on smaller screens. Made documentation ToC collapsible as well.

Important
Breaking change

Navigation block on documentation pages has changed its selector from .nav-sidebar to .docs-nav; sites customizing that have to update the selector in HTML/CSS.

1.1.16

Improved formatting of code snippets, lists, tables and admonition blocks.

1.1.14-15

Incremental improvements to content presentation & formatting:

  • More consistent formatting of code snippets in docs and elsewhere on the site

  • Nicer styling of tables in article bodies

  • Whitespace consistency here and there

  • Better formatting of TBD labels

1.1.13

  • More consistent formatting of code snippets in docs and elsewhere on the site

  • Fixed a problem with fetched software documentation not always being rendered as part of project site

1.1.12

  • Some changes in SASS structure aimed to improve customizability of Open Project framework-based site UIs

1.1.11

  • Even faster processing when refresh_remote_data is set to 'skip'

  • More flexible customization means for sites using the OP framework

  • Layout improvements across screen widths

  • Minor documentation page layout & content formatting improvements

1.1.10

Synchronized versions & centralized change log

  • Each theme version will require (in its gemspec) the exact helpers library version

  • Theme’s CHANGELOG will reflect the development of Open Project framework regardless of whether the actual changes belong to theme or helpers gem

Fixes to multi-site data integration

  • A few issues in data-fetching logic were fixed, now certain edge cases (such as missing software docs) are handled better and (re)generation of sites, especially for projects with many software packages and for project hubs, should be faster on average.

  • Site’s _config.yml now supports optional string flag refresh_remote_data with three possible values: 'always', 'last-resort' (default), and 'skip'.

 — The default 'last-resort' choice means site build will attempt to fetch remote data (such as last software update timestamp, software docs, hub logos, etc.) when there is no local copy.

 — 'always' may be helpful during development if you have a local copy from previous build, but the remote data has changed and you want your local sites to reflect that.

 — 'skip' will always leave local data intact and not attempt to contact remote repositories, which would speed up regeneration during debugging or development where you know you have a local copy alreay fetched as needed (otherwise it’s likely going to break your build).

1.1.9

Build-related fix:

  • Correct exclude to ensure hub site doesn’t try to build software docs

Software documentation improvements:

  • Fixes to hosted (‘internal’) documentation page layout

  • Slightly more expressive formatting on documentation pages (highlighting “tip” blocks)

  • Improvements to how external documentation links are shown

Various fixes and improvements:

  • Make hamburger menu script external to facilitate CSP policy implementation

  • Minor changes to layout & default copy

  • Remove redundant ARIA role definition from presentational divs

1.1.8

  • Minor improvements to layout & default copy phrasing here and there

  • Correct excludes in default _config.yml definition in the theme to prevent Jekyll from trying to build what shouldn’t be built

1.1.7

Improved documentation layout:

  • Show external link markers

  • Fix an issue with “Documentation” header shown on item docs landing even if no documentation pages exist

Bugfixes:

  • Show tags in human-readable form (with underscores replaced to spaces) on software & spec cards

1.1.6

Much improved documentation layout:

  • Docs landing page features commonly used external links (external API reference docs, repository, IETF datatracker, etc.) more prominently

  • Fixed how code samples are shown in documentation pages

  • Fixed documentation page layout issues on narrower screens

1.1.5

A couple of layout tweaks:

  • Preserve clickability of active item in top menu

  • Make software documentation/spec page layout fit narrow screens

1.1.4

  • A few improvements to sites’ layout on narrow screens

1.1.3

  • A few appearance updates, including more elegant layout and hamburger menu on narrower screens.

1.1.2

  • Fixed an issue preventing hub site build if child project sites’ SCSS imported files from outside the assets directory

1.1.1

  • Fixed an issue breaking Jekyll build on sites which do not have a scripts.html include

1.1.0

Minor features:

  • Update default layout to allow sites plug custom JS via scripts.html include

  • Add an ID to default <link> element (allows sites to change the stylesheet from a script for custom theming)

Other changes:

  • Changed site type and layout classes added on <body> by the theme, aiming to make the selectors more explicit and clear.

    **BREAKING:** This breaks custom styling on sites where it relies
on old-style `body.layout-layoutname`, `body.hub`, `body.project` selectors.
    Corresponding new selectors would be
`body.layout--layoutname`, `body.site--hub`, `body.site--project`.

1.0.10

  • Implemented optional key feature_with_priority for software and specs (#28)

  • Added CHANGELOG