Create NotePlugin, add base Plugin, update MD syntax

Author: JJdeGroot

github.js

@@ -5,8 +5,9 @@ import markdownit from 'markdown-it';
 import ejs from 'ejs';
 import open from 'open';
 
-import { GithubPlugin } from './github.js';
-import { WcagPlugin } from './wcag.js';
+import { GithubPlugin } from './plugins/github.js';
+import { NotePlugin } from './plugins/note.js';
+import { WcagPlugin } from './plugins/wcag.js';
 
 const root = process.cwd();
 
@@ -33,7 +34,8 @@ const readFiles = async (folder, extension) => {
 // Execute: init plugins, read files, render HTML
 const execute = async () => {
   console.log(`Initializing custom plugins...`);
-  const githubPlugin = GithubPlugin.init('https://github.com/w3c/matf');
+  const githubPlugin = await GithubPlugin.init('https://github.com/w3c/matf');
+  const notePlugin = await NotePlugin.init();
   const wcagPlugin = await WcagPlugin.init('wcag', 'https://www.w3.org/TR/WCAG22/');
   const wcag2ictPlugin = await WcagPlugin.init('wcag2ict', 'https://www.w3.org/TR/wcag2ict-22/');
 
@@ -42,6 +44,7 @@ const execute = async () => {
     html: true 
   })
   .use(githubPlugin)
+  .use(notePlugin)
   .use(wcagPlugin)
   .use(wcag2ictPlugin);
 

index.html

@@ -0,0 +1,56 @@
+import { Plugin } from './plugin.js';
+
+/**
+ * The GithubPlugin adds a new markdown tag to render GitHub issues.
+ * For example, the `[issue:71]` markdown will render issue #71 as a note with a link.
+ */
+export class GithubPlugin extends Plugin {
+  constructor(url) {
+    super('issue');
+    this.url = url;
+  }
+
+  /**
+   * Initializes the plugin with the specified GitHub repository URL.
+   * @param {string} url - The GitHub repository URL (e.g., `https://github.com/w3c/matf`).
+   * @returns {function} - An initialized `GithubPlugin` function.
+   */
+  static async init(url) {
+    return new GithubPlugin(url).plugin();
+  }
+
+  /**
+   * Defines the regex for matching `[issue:<number>]`.
+   * @returns {RegExp} - The regex for matching the issue syntax.
+   */
+  regex() {
+    return /^\[issue:(\d+)\]/;
+  }
+
+  /**
+   * Populates the token with issue number and link.
+   * @param {Array} match - The regex match result.
+   * @param {object} token - The token to populate.
+   */
+  process(match, token) {
+    const number = match[1];
+
+    token.number = number;
+    token.link = `${this.url}/issues/${number}`;
+  }
+
+  /**
+   * Renders the token as a Note with a link to the issue on Github.
+   * @param {object} token - The token to render.
+   * @returns {string} - The rendered HTML string.
+   */
+  render(token) {
+    return `
+      <div class="note" title="Work In Progress">
+        <a href="${token.link}" target="_blank">
+          Read issue #${token.number} on GitHub
+        </a>
+      </div>
+    `;
+  }
+}

matf.js

@@ -0,0 +1,55 @@
+import { Plugin } from './plugin.js';
+import markdownit from 'markdown-it';
+
+/**
+ * The Note plugin adds a new markdown tag to render a Note.
+ * For example, the `[note:markdown]` markdown will render a Note containing the given `markdown`.
+ */
+export class NotePlugin extends Plugin {
+  constructor() {
+    super('note');
+    this.md = markdownit({ 
+      html: true 
+    })
+  }
+
+  /**
+   * Initializes the NotePlugin without any additional setup.
+   * @returns {Promise<{function}>} - An initialized `NotePlugin` function.
+   */
+  static async init() {
+    return new NotePlugin().plugin();
+  }
+
+  /**
+   * Defines the regex for matching `[note:<markdown>]`.
+   * @returns {RegExp} - The regex for matching the note syntax.
+   */
+  regex() {
+    return /\[note:(.*)?\]/;
+  }
+
+  /**
+   * Processes the matched content and populates the token with raw markdown.
+   * @param {Array} match - The regex match result.
+   * @param {object} token - The token to populate.
+   */
+  process(match, token) {
+    token.content = match[1].trim(); // Extract the markdown content from the match
+  }
+
+  /**
+   * Renders the token into HTML by converting markdown to HTML for the content.
+   * @param {object} token - The token to render.
+   * @returns {string} - The rendered HTML string.
+   */
+  render(token) {
+    // Use markdown-it to render the content into HTML
+    const html = this.md.render(token.content);
+    return `
+      <div class="note">
+        ${html}
+      </div>
+    `;
+  }
+}

plugins/github.js

@@ -0,0 +1,76 @@
+/**
+ * Plugin: A base class with shared logic for custom markdown-it plugins.
+ */
+export class Plugin {
+  constructor(tag) {
+    this.tag = tag;
+  }
+
+  /**
+   * Initializes the plugin with any required setup.
+   * Subclasses should override this method to return a fully initialized plugin.
+   * @param {...*} args - Arguments required to initialize the plugin.
+   * @returns {Promise<Plugin>} - A promise resolving to an initialized plugin instance.
+   */
+  static async init(...args) {
+    throw new Error(`Subclass ${this.name} must implement 'async static init(... args)'`);
+  }
+
+  /**
+   * Returns the markdown-it plugin function.
+   * @returns {function} - A markdown-it plugin function.
+   */
+  plugin() {
+    return (md) => {
+      // Register the parsing rule for the tag
+      md.inline.ruler.before('emphasis', this.tag, (state, silent) => {
+        const regex = this.regex();
+        const match = state.src.slice(state.pos, state.posMax).match(regex);
+
+        if (!match) return false; // No match found
+        if (silent) return true; // Validate without modifying state
+
+        const token = state.push(`${this.tag}_details`, '', 0);
+        this.process(match, token);
+
+        state.pos += match[0].length; // Move the parser position forward
+        return true;
+      });
+
+      // Register the rendering rule for the tag
+      md.renderer.rules[`${this.tag}_details`] = (tokens, idx) => {
+        const token = tokens[idx];
+        return this.render(token);
+      };
+    };
+  }
+
+  /**
+   * Returns the regex for matching the tag.
+   * Subclasses should override this method.
+   * @returns {RegExp} - The regex for matching the tag.
+   */
+  regex() {
+    throw new Error(`Subclass ${this.name} must implement 'regex()'`);
+  }
+
+  /**
+   * Processes the regex match and populates the token with data.
+   * Subclasses should override this method.
+   * @param {Array} match - The regex match result.
+   * @param {object} token - The token to populate.
+   */
+  process(match, token) {
+    throw new Error(`Subclass ${this.name} must implement 'process(match, token)'`);
+  }
+
+  /**
+   * Renders the token to HTML.
+   * Subclasses should override this method.
+   * @param {object} token - The token to render.
+   * @returns {string} - The rendered HTML string.
+   */
+  render(token) {
+    throw new Error(`Subclass ${this.name} must implement 'render(token)'`);
+  }
+}

plugins/note.js

@@ -0,0 +1,125 @@
+import { Plugin } from './plugin.js';
+import * as cheerio from 'cheerio';
+import * as puppeteer from 'puppeteer';
+
+/**
+ * The WCAG plugin adds a new markdown tag which can render sections of WCAG.
+ * For example, the `[wcag:status-messages]` markdown will render the `status-messages` section.
+ */
+export class WcagPlugin extends Plugin {
+  constructor(tag, url, html) {
+    super(tag);
+    this.url = url;
+    this.html = html;
+    this.$ = cheerio.load(html);
+  }
+
+  /**
+   * Initializes the WcagPlugin by fetching and preparing the HTML content from the provided URL.
+   * @param {string} tag - The tag used in markdown (e.g., `wcag` or `wcag2ict`).
+   * @param {string} url - The URL to fetch content from (e.g., `https://www.w3.org/TR/WCAG22/`).
+   * @returns {Promise<{function}>} - An initialized `WcagPlugin` function.
+   */
+  static async init(tag, url) {
+    const html = await WcagPlugin.fetchHtml(url);
+    return new WcagPlugin(tag, url, html).plugin();
+  }
+
+  /**
+   * Fetches the rendered HTML from the given URL using Puppeteer.
+   * @param {string} url - The URL to fetch.
+   * @returns {Promise<string>} - The rendered HTML content.
+   */
+  static async fetchHtml(url) {
+    console.log(`Fetching rendered HTML for: ${url}`);
+    const browser = await puppeteer.launch({ headless: true });
+    const page = await browser.newPage();
+
+    try {
+      await page.goto(url, { waitUntil: ['load', 'networkidle0'] });
+      const html = await page.content();
+      await browser.close();
+      return html;
+    } catch (error) {
+      console.error(`Error fetching ${url}:`, error);
+      await browser.close();
+      return `<p>Error loading content from ${url}</p><p>${error}</p>`;
+    }
+  }
+
+   /**
+   * Defines the regex for matching `[<tag>:<identifier>]`.
+   * @returns {RegExp} - The regex for matching the note syntax.
+   */
+  regex() {
+    return new RegExp(`\\[${this.tag}:([a-zA-Z0-9-_\\.]+)\\]`);
+  }
+
+  /**
+   * Processes the matched content and populates the token with id, link, header and content.
+   * @param {Array} match - The regex match result.
+   * @param {object} token - The token to populate.
+   */
+  process(match, token) {
+    const id = match[1];
+    const section = this.extract(id);
+
+    token.id = id;
+    token.link = `${this.url}#${id}`;
+    token.header = section.header;
+    token.content = section.content;
+  }
+
+  /**
+   * Renders the token into HTML with an expand/collapse component.
+   * @param {object} token - The token to render.
+   * @returns {string} - The rendered HTML string.
+   */
+  render(token) {
+    return `
+      <details class="wcag">
+        <summary>
+          <strong>${this.tag.toUpperCase()}:</strong> ${token.header}
+        </summary>
+        <blockquote cite="${token.link}">
+          <div>${token.content}</div>
+        </blockquote>
+        <footer>
+          <cite>
+            <a href="${token.link}" target="_blank">${token.link}</a>
+          </cite>
+        </footer>
+      </details>
+    `;
+  }
+
+  /**
+   * Renders the token into HTML by converting markdown to HTML for the content.
+   * @param {string} id - The identifier for the section.
+   * @returns {object} - An object containing the `header` and `content` of the section.
+   */
+  extract(id) {
+    const $section = this.$(`#${id}`);
+    if (!$section.length) {
+      throw new Error(`Section not found: ${id}`);
+    }
+
+    const header = $section.find('h1, h2, h3, h4, h5, h6').first().text();
+    $section.find('.header-wrapper, .doclinks, .conformance-level').remove();
+    $section.find('a').each((_, anchor) => {
+      const href = this.$(anchor).attr('href');
+      if (href) {
+        this.$(anchor).attr('target', '_blank');
+        if (!/^[\w]+:\/\//.test(href)) {
+          const fullUrl = new URL(href, this.url).href;
+          this.$(anchor).attr('href', fullUrl);
+        }
+      }
+    });
+
+    return {
+      header,
+      content: $section.html(),
+    };
+  }
+}