Table of Contents
Tip

The docs as explained here are used in multiple projects, but documented only once for better maintenance. When applying this to other projects, remember that some things such as the name, repository, or paths are a bit different.

Docs: Technical Implementation

Warning

This is a technical documentation about how the documentation system works. It helps the core team understand how to maintain and enhance the documentation system.

It's not meant for most contributors, as it's too technical.

Basics

  1. The documentation is built with DocFX.

  2. When compiling, it will take the C# code and the markdown files and merge them together...

  3. ...and create a static HTML documentation which can be hosted anywhere - often on GitHub pages.

The Parts that Make it Work

Since this is a large documentation it needs a bit more than just the standard DocFX setup. Here is an overview as to what is really implemented:

  1. DocFX will build everything based on the configuration in docfx.json, filterConfig.yml and xrefmap.yml
    ➡️ Configuration

  2. C# Code Docs generation and Merging with additional docs is very sophisticated.
    ➡️ C# Code Docs

  3. JavaScript Code Docs generation and Merging with additional docs is a beast! ➡️ JavaScript Code Docs

  4. The Templates generate everything, add JS and much more
    ➡️ Templates

  5. We have some custom magic to improve the C# API TOC
    ➡️ TOC Customizations

  6. The /templates/[project]/src has TypeScript and SASS which is compiled with WebPack to the /public folder
    ➡️ see TypeScript, CSS, WebPack Customizations

  7. We implemented a special Permalink-System TODO: @iJungleboy

  8. Most projects also support version-switching, so you can switch between versions of the documentation TODO: @iJungleboy

History of this Docs Setup

2024

Note: we only started documenting this in 2024-12, so it's incomplete.

Reduced Time-To-Redirect on XREF to 1 Second

Previously the time to redirect was 3 seconds. We reduced it to 1 second.

  • /templates/shared-global/src/scripts/xref/xref.ts

Changed: 2024-12-12, @iJungleboy

Made API-Docs TOC Sidebar not Wrap

Added the api-toc-sidebar-menus.scss to prevent the API-Docs TOC from wrapping.

  • /templates/shared-global/src/styles/api-toc-sidebar-menu.scss
  • /templates/shared-global/src/styles/_index.scss

Changed: 2024-12-12, @iJungleboy

Added SVG helpers for colored logos

Added some JavaScripts to inline SVGs on img tags with the class svg.

This helps for both the logo and images added like this, so that they will be inlined and behave according to the CSS. It's especially useful when the SVG uses currentColor in it's own CSS.

  • /templates/shared-global/src/scripts/svgs/svg-importer.ts

Changed: 2024-12-10, @iJungleboy

Created Attribution System

We created an attribution system to show who wrote which part of the documentation.

Changed: ca. 2024-12-05, @iJungleboy

Standardized Entire Setup

We put all customizations and docs-instructions in the 2sxc docs only, to consolidate everything from 2sxc, Oqtane, RazorBlade and cre8magic.

Implementation:

  1. Everything shared is now in /templates/shared-global
  2. The /templates/[project]/src is now the only place for project-specific customizations

Changed: 2024-12-05, @iJungleboy, @tvatavuk

We created the <div gallery="name"><!-- img list --></div> feature to create galleries with previews etc.

Changed: ca. 2024-12-01, @iJungleboy

Added Lightbox with Fancybox

We added the Fancybox lightbox to the system, so that images can be opened in a lightbox.

Changed: ca. 2024-11, @iJungleboy

Added Razor/Blazor Syntax Coloring

We added the Razor/Blazor syntax coloring to the system, so that code can be colored.

Changed: ca. 2024-06, @tvatavuk

Edit this page