Beta Changelog

Beta changelog

The FIL specs team's main focus was to solve the issues that prevented authors from editing the spec content. We reduced complexity, did proper dependency management, added features to ensure consistency, added support for new tools and much more described in the list below. There is comprehensive, concise and easy-to-follow documentation for all the features that need explanation for the spec editors in the front-page README of the specs repo.

The specs site is now robust and ready to be used by the teams without running into unexpected errors and most importantly without having to keep multiple sources of truth in sync! A summary of the features includes:

Tooling & Syntax

• Simpler tooling with just Hugo cli plus assets pipeline with watcher
• Standard Hugo folder tree reducing the surface for build issues
• Seamless control over dependencies with npm and Go Modules
• Spec editing can be done almost entirely using simple markdown syntax. We now have only 3 custom Hugo Shortcodes that are completely optional. This reduces significantly the editing complexity for the spec editors, as well as surface for errors when building the site.
• References to sections can be done with normal markdown links and are validated by Hugo and if any of the links is broken, CI or the local server will break and output a descriptive error, so that the spec author can correct before committing changes.
  • All existing content has been reviewed multiple times and all broken or missing links have been fixed.
• Support for latex
  • katex is used to enable latex support for math content
  • katex only loads when the latex content is in the viewport, making full page load much faster and less jumpy, i.e., only sections that include math are rendered by katex.
• New markdown linter with some custom lint rules to ensure consistency in the content markdown.
  • This runs in the CI as a test.

Status Dashboards

• "Spec Status Overview" dashboard with information for each section: Spec State, Theory Audit and Conformance Tests (TBA)
  • Audit reports are linked from the respective cells, together with the date of the latest audit.
  • Conformance Tests will be pulled from the respective Oni test repositories
  • Overall progress bar for spec completeness, built directly from spec frontmatter values
  • Frontmatter properties in spec files to feed the values needed to build the dashboard and progress bar
  • Dashboard generated and updated automatically from ToC. No need to edit separate files to update the dashboard, as dashboard values are pulled from the frontmatter.
• Section status badge in all sections that appear in the dashboard with the status being pulled from the frontmatter, hence, automatically updated once frontmatter is edited.
• Separate "Implementation Status" dashboard with status information for Lotus, Fuhon, Forest and go-filecoin

Diagrams and Code blocks

• Mermaid and Dot processing pipelines (more can be added in the future) nicely integrated with Hugo server for development and content editing.
• Diagrams and images have a nice lightbox with zoom and pan.
• Code blocks can now import Hugo Modules (this is basically go modules wrapped by Hugo) to embed code that is always up to date with the upstream source.
  • We will enable daily deploys to keep code blocks up to date, as they're pulled from the respective repositories.
  • Adding code blocks from a new repository is as easy as adding a new Hugo module and linking to it. The procedure is trivial and explained in the README of the specs repo.

Document Hierarchy

• Section numbering pulled from ToC, so that ToC is automatically updated once sections are reorganised. No need to edit separate files to keep things in sync.
• Section deep-linking integrated.
• Single page rendering is now stable and section structure is reflected in the ToC.
• Clear position in the ToC at all times as the reader scrolls down

Misc

• IPFS deploy for production and previews in PRs and commits. This enables permanent links to a full spec deploy for each commit. Crypto team already using this for audits.
• Service Worker was added to support offline cases plus install as an OS App.
• New styles and code highlighting integrated, plus several other UI improvements.
• Multi language support is available.

Overall writing experience and consistency has been significantly improved, as already testified by FIL teams and with Hugo validations and the Markdown linter it is much harder for writer to do something wrong without getting a descriptive error.