Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 3x 3x 3x 3x 3x 4x 4x 3x | /**
* Maps notice type names to their display labels.
* This allows for custom formatting of notice type labels in the rendered output.
*
* @param {string} type - The notice type identifier (e.g., 'informative')
* @returns {string} The formatted display label (e.g., 'INFORMATIVE SECTION')
*/
function getNoticeDisplayLabel(type) {
const displayLabels = {
'informative': 'INFORMATIVE SECTION'
};
return displayLabels[type] || type.toUpperCase();
}
/**
* Configures and applies external markdown-it plugins to a given markdown-it instance.
* This module centralizes plugin loading to reduce complexity in the main index.js file.
* It handles only the external npm plugins (e.g., markdown-it-attrs), not custom extensions.
*
* @param {Object} md - The markdown-it instance to configure
* @param {Object} config - Configuration object (e.g., for TOC anchor symbol)
* @param {Object} containers - The markdown-it-container instance (passed to avoid re-requiring)
* @param {Object} noticeTypes - Object defining valid notice types (e.g., { note: 1, issue: 1, ... })
* @param {Object} noticeTitles - Object to track notice titles (passed to maintain state)
* @returns {Object} The configured markdown-it instance
*/
function configurePlugins(md, config, containers, noticeTypes, noticeTitles, setToc) {
// Apply attribute support for elements (e.g., {.class} syntax)
// This enables adding CSS classes or IDs to markdown elements without HTML.
md.use(require('markdown-it-attrs'));
// Enable chart rendering from code blocks (e.g., ```chart ... ```)
// Useful for embedding diagrams directly in markdown.
md.use(require('markdown-it-chart').default);
// Support definition lists (e.g., term\n: definition)
// Enhances standard markdown with formal definition formatting.
md.use(require('markdown-it-deflist'));
// Add reference-style links and footnotes
// Allows cleaner link management in long documents.
md.use(require('markdown-it-references'));
// Enable Font Awesome icons (e.g., :fa-icon:)
// Integrates icon rendering for visual enhancements.
md.use(require('markdown-it-icons').default, 'font-awesome');
// Support <ins> tags for inserted text (e.g., ++text++)
// Useful for highlighting additions in specs.
md.use(require('markdown-it-ins'));
// Support <mark> tags for highlighted text (e.g., ==text==)
// Helps emphasize important terms or sections.
md.use(require('markdown-it-mark'));
// Enable textual UML diagrams (e.g., @startuml ... @enduml)
// Allows embedding diagrams without external tools.
md.use(require('markdown-it-textual-uml'));
// Support subscript text (e.g., H~2~O)
// Essential for scientific or technical writing.
md.use(require('markdown-it-sub'));
// Support superscript text (e.g., E=mc^2^)
// Complements subscript for mathematical expressions.
md.use(require('markdown-it-sup'));
// Enable task lists (e.g., - [x] Task)
// Great for checklists in documentation.
md.use(require('markdown-it-task-lists'));
// Support multi-line tables with rowspan/colspan
// Extends basic tables for complex layouts.
md.use(require('markdown-it-multimd-table'), {
multiline: true,
rowspan: true,
headerless: true
});
// Configure notice containers (e.g., ::: note ... :::)
// Uses the passed containers plugin for custom blocks like warnings or examples.
md.use(containers, 'notice', {
validate: function (params) {
// Check if the notice type is valid (e.g., 'note', 'issue')
let matches = params.match(/(\w+)\s?(.*)?/);
return matches && noticeTypes[matches[1]];
},
render: function (tokens, idx) {
// Render opening or closing tags for notices
let matches = tokens[idx].info.match(/(\w+)\s?(.*)?/);
if (matches && tokens[idx].nesting === 1) {
let id;
let type = matches[1];
if (matches[2]) {
// Custom ID from title
id = matches[2].trim().replace(/\s+/g, '-').toLowerCase();
if (noticeTitles[id]) id += '-' + noticeTitles[id]++;
else noticeTitles[id] = 1;
} else {
// Auto-generated ID
id = type + '-' + noticeTypes[type]++;
}
return `<div id="${id}" class="notice ${type}"><a class="notice-link" href="#${id}">${getNoticeDisplayLabel(type)}</a>`;
} else {
return '</div>\n';
}
}
});
// Add syntax highlighting with Prism.js
// Enhances code blocks with colorized syntax.
md.use(require('markdown-it-prism'));
// Heading permalinks + TOC (via callback for template injection).
// Replaces markdown-it-toc-and-anchor, which is incompatible with markdown-it 14.
const markdownItAnchor = require('markdown-it-anchor');
md.use(markdownItAnchor, {
permalink: markdownItAnchor.permalink.linkInsideHeader({
symbol: config.specs[0].anchor_symbol || '§',
class: 'toc-anchor d-print-none',
placement: 'before',
space: true
})
});
md.use(require('markdown-it-toc-done-right'), {
listClass: 'toc',
listType: 'ul',
level: [2, 3, 4],
// Permalink spacing can leak into heading text; keep TOC labels clean.
format: (heading, htmlencode) => htmlencode(heading.trim()),
callback: (html) => {
// Keep the legacy shape expected by #toc CSS/JS: bare <ul class="toc">…</ul>
const match = html && html.match(/<ul class="toc">[\s\S]*<\/ul>/);
let tocHtml = match ? match[0] : (html || '');
tocHtml = tocHtml.replace(/<ul class="toc">/g, '<ul>').replace('<ul>', '<ul class="toc">');
setToc(tocHtml);
}
});
// Enable KaTeX for math rendering (e.g., $$...$$)
// Supports inline and block math expressions.
md.use(require('@traptitech/markdown-it-katex'));
return md;
}
module.exports = { configurePlugins }; |