HTML Explanatory Documents

Text

To supplement the content of explanations and Japanese expressions, we recommend using the following skills in combination:

```
explain
```
: Term definitions, explanation granularity, and structure when explaining concepts and mechanisms
```
japanese-tech-writing
```
: Structure and writing standards for Japanese technical documents, articles, and explanatory texts
```
cognitive-rhythm-writing
```
: Writing standards for long texts that require pacing as readable materials

All of these are recommended skills and not mandatory dependencies for

html

Deliverables

Create HTML
Ensure it can be rendered directly by a browser without building
Follow the specified save location if provided; save to the current working directory if no location is specified
Use the filename format
```
{yyyymmdd}-{kebab-case-representing-content}.html
```
. Do not change the name when updating an existing file
Follow the instructions of the higher-level skill referencing this skill for rules regarding individual document management systems, metadata, viewers, and publication destinations

Design System

Check

design-system/component-samples.html

before creating. The component set is based on

design-system/document.css

, and the formula copy function is based on

design-system/math-copy.js

By default, place necessary files together with the deliverable and load them using the following relative paths. If a higher-level skill specifies a path for shared assets, prioritize that specification.

html

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Ubuntu+Sans:wght@400;500;700&family=Noto+Sans+JP:wght@400;500;700&family=Ubuntu+Mono:wght@400;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="./design-system/document.css">
<script src="./design-system/math-copy.js"></script>
<script async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script>
<script>document.addEventListener("DOMContentLoaded", () => hljs.highlightAll());</script>

The main rules are as follows:

Background color is
```
#FAF9F6
```
. Components are based on white backgrounds, black borders, and rounded corners
Use Ubuntu Sans and Noto Sans JP for natural language, and Ubuntu Mono for code, URLs, and dates
Limit colored text to link blue
```
#2990DA
```
and accent red
```
#D63A2F
```
In principle, limit red emphasis to one occurrence per page
Syntax highlighting and code diff colors are excluded from this restriction as functional colors that distinguish meaning
Maintain balanced margins on all sides
Use
```
.mb-quote
```
for citations, placing the original text and translation side by side vertically with the same font size and color
Use
```
.mb-chip
```
only for listing parallel proper nouns or category names
Do not use emojis or arrow characters as symbols. Draw necessary symbols using inline SVG
Use tables for short correspondence relationships, with a maximum of 3 columns as a basic rule
Add
```
.mb-rowlabel
```
to row header cells to prevent line breaks within words
Use
```
pre.mb-diff
```
for code diffs, explain the reason for changes in prose before showing necessary fragments
Keep page-specific
```
<style>
```
to a minimum, such as for adjusting figure placement

Structure and Format

Use side-by-side comparison, illustrations, timelines, summaries, and collapsible sections appropriately according to the subject of the explanation. Do not unnecessarily convert one-way simple procedures into flowcharts.

The basic structure is as follows in this order:

Glossary
Background
Main argument
Specific examples
Supplements, limitations, and related matters

Place a

.mb-toc

table of contents after the h1 and lead paragraph, and assign corresponding

id

attributes to each h2. Place the glossary in

aside.mb-glossary

within

.mb-wrap

. Define technical terms in 1-2 sentences before using them in the main text.

Figures

```
.mb-figure
```
is an outer frame that groups visual materials such as images and SVG with captions. It does not refer to specific shapes or "boxes connected by arrows"
Use
```
.mb-figure-frame
```
as the display area for visual materials, and
```
figcaption
```
as the display area for figure numbers, explanations, and sources
If there is an important figure in the original source, cite it clearly with the source indicated
Do not create imitation figures if the original source's figures are available
Create custom figures as inline SVG; do not use ASCII art
Use black line drawings as the base and place them in
```
.mb-figure-frame
```
Prioritize vertical orientation when there are a large number of nodes
Avoid configurations where arrows cross
Express simple sequential procedures as numbered explanations

Code

Always load Highlight.js and apply syntax highlighting according to the language

Always add language classes such as

language-javascript

language-python

language-html

pre code

Add
```
language-plaintext
```
to text that does not require highlighting
Do not decorate code with custom coloring; use the
```
.hljs-*
```
rules in
```
document.css
```
Add
```
nohighlight
```
to
```
pre.mb-diff code
```
and use diff-specific colors and line prefix symbols

Formulas

Use MathJax 3
Use
```
$...$
```
for inline formulas and
```
$$...$$
```
for display formulas
Use
```
\boldsymbol{...}
```
for vectors and matrices
Do not decorate scalars, subscripts, or set names
Use
```
\mathtt{...}
```
for named operations, and use standard LaTeX commands as-is
Enable copying of the original LaTeX text from all formulas using
```
math-copy.js
```
Do not redefine
```
window.MathJax
```
on the page side
Do not arbitrarily replace unknown commands with alternative notations

Printing and PDF

Use

@media print

document.css

for print compatibility. Execute

render-pdf.sh

only when explicitly requested by the user to convert to PDF.