(test) allow skipped markup tests with .skip suffix

docs/building-testing.rst

@@ -103,6 +103,21 @@ To generate reference rendering use the Developer tool located at
 ``tools/developer.html``. Make sure to explicitly select your language in the
 drop-down menu, as automatic detection is unlikely to work in this case.
 
+Skipped markup tests (unsupported edge cases)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The suite must not ship failing markup tests. For edge cases that are not
+supported yet (or are tracked as future work), commit the pair with a
+``.skip`` suffix on the base name:
+
+* ``test/markup/<language>/<test_name>.skip.txt``
+* ``test/markup/<language>/<test_name>.skip.expect.txt``
+
+These are registered with Mocha as skipped tests: they appear in the report
+but do not fail CI. Prefer this over omitting the case entirely so the gap
+stays visible. Link a tracking issue in the PR or a nearby comment when you
+add a skip.
+
 
 Building and Testing with Docker
 --------------------------------

test/markup/index.js

@@ -21,8 +21,12 @@ function testLanguage(language, {testDir}) {
     filenames.forEach(function(filename) {
       const testName = path.basename(filename, '.expect.txt');
       const sourceName = filename.replace(/\.expect/, '');
+      // `name.skip.txt` + `name.skip.expect.txt` marks an unsupported edge case
+      // (see docs/building-testing.rst). Kept for a roadmap without failing CI.
+      const skipped = testName.endsWith('.skip');
+      const run = skipped ? it.skip : it;
 
-      it(`should markup ${testName}`, function(done) {
+      run(`should markup ${testName}`, function(done) {
         const sourceFile = fs.readFile(sourceName, 'utf-8');
         const expectedFile = fs.readFile(filename, 'utf-8');