Skip to content

Update documentation and package for Validation #377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SteveLLamb merged 7 commits into from
Jan 30, 2026
Merged

Update documentation and package for Validation #377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0a8b710
Update documentation and package for Validation
SteveLLamb Jan 29, 2026
bb94f72
fix errors
SteveLLamb Jan 29, 2026
e8a9b8a
bump release
SteveLLamb Jan 29, 2026
283e792
test npm html validator
SteveLLamb Jan 30, 2026
2fbea42
Revert "test npm html validator"
SteveLLamb Jan 30, 2026
debd585
remove trailing slashes
SteveLLamb Jan 30, 2026
f36d95e
roll to pub
SteveLLamb Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .smpte-build.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"latestEditionTag": "2.0.0-rc.1"
"latestEditionTag": "20260127-pub"
}
135 changes: 116 additions & 19 deletions doc/main.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,20 @@
<html>

<head itemscope="itemscope" itemtype="http://smpte.org/standards/documents">
<meta charset="utf-8" />
<meta http-equiv="x-ua-compatible" content="ie=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script type="module" src="../smpte.js"></script>
<meta itemprop="pubType" content="AG" />
<meta itemprop="pubNumber" content="26" />
<!-- <meta itemprop="pubPart" content="XX" /> -->
<meta itemprop="pubState" content="pub" />
<!-- meta itemprop="pubStage" content="WD" / -->
<meta itemprop="pubConfidential" content="no" />
<!--< meta itemprop="pubTC" content="XX" /> -->
<meta itemprop="pubSuiteTitle" content="HTML Pub" />
<meta itemprop="pubDateTime" content="2026-01-27" />
<!-- <meta itemprop="pubRevisionOf" content="SMPTE ST XXXX-Y:ZZZZ" /> -->
<meta itemprop="pubType" content="AG">
<meta itemprop="pubNumber" content="26">
<!-- <meta itemprop="pubPart" content="XX"> -->
<meta itemprop="pubState" content="pub">
<!-- meta itemprop="pubStage" content="WD"> -->
<meta itemprop="pubConfidential" content="no">
<!--< meta itemprop="pubTC" content="XX"> -->
<meta itemprop="pubSuiteTitle" content="HTML Pub">
<meta itemprop="pubDateTime" content="2026-01-30">
<!-- <meta itemprop="pubRevisionOf" content="SMPTE ST XXXX-Y:ZZZZ"> -->
<title>Tooling and documentation for HTML documents</title>
</head>

Expand Down Expand Up @@ -1317,9 +1317,11 @@ <h4>Inline code fragments</h4>

<section id="sec-tooling">
<h2>Tooling</h2>
<section id="sec-tooling-general">
<h3>General</h3>

<section id="sec-tooling-overview">
<h3>Overview</h3>
<h4>Overview</h4>

<p>The SMPTE HTML publication tooling consists of several components:</p>

Expand All @@ -1336,7 +1338,7 @@ <h3>Overview</h3>
</section>

<section id="sec-tooling-rendering">
<h3>Rendering</h3>
<h4>Rendering</h4>

<p>At the heart of the tooling is the rendering code at <code>smpte.js</code>.</p>

Expand All @@ -1345,7 +1347,7 @@ <h3>Rendering</h3>
</section>

<section id="sec-building">
<h3>Building</h3>
<h4>Building</h4>

<p>Building the document for publication involves the following steps:</p>

Expand Down Expand Up @@ -1398,7 +1400,7 @@ <h3>Building</h3>
</section>

<section id="sec-gh-integration">
<h3>GitHub integration</h3>
<h4>GitHub integration</h4>

<p>To automatically create and upload to S3 the clean and redline copies of the document when commits are pushed to GitHub,
the workflow file at <a href="#figure-workflow-file"></a> is stored at <code>.github/workflows/main.yml</code> in the
Expand Down Expand Up @@ -1435,7 +1437,7 @@ <h3>GitHub integration</h3>
</section>

<section id="sec-aws-integration">
<h3>Amazon AWS integration</h3>
<h4>Amazon AWS integration</h4>

<p>The tooling uploads publication artifacts to an S3 bucket according to the following parameters:</p>

Expand Down Expand Up @@ -1485,7 +1487,7 @@ <h3>Amazon AWS integration</h3>
</section>

<section id="sec-tooling-git-hooks">
<h3>Git commit hooks</h3>
<h4>Git commit hooks</h4>

<p>It is advisable to install the git commit hook listed at <a href="#figure-pre-commit-hook"></a>. It detects errors before a
document can be committed.</p>
Expand All @@ -1495,7 +1497,102 @@ <h3>Git commit hooks</h3>
<figcaption>Pre-commit hook that validates the main element.</figcaption>
</figure>
</section>
</section>
<section id="sec-tooling-local">
<h3>Using tooling locally</h3>

<section id="sec-tooling-local-overview">
<h4>Overview</h4>
<p>Many of the features and automatic formatting available in the tooling is present and available when working locally. This allows an editor to create and edit a valid HTML document before pushing to a repo and encountering an error.</p>
<p>It is recommended to utilize VS Code (<a>https://code.visualstudio.com/</a>) as your local HTML editor, using the Live Preview extension (<a>https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server</a>), which shows some validation in real-time for an editor.</p>
<p>Other useful extension(s) for VS Code are:</p>
<ul>
<li>Git Graph (visual aid) - <a>https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph</a></li>
</ul>

</section>

<section id="sec-tooling-local-install">
<h4>Installation and prerequisites</h4>
<p>
To use the full features locally either on command line, or in termimal (also available inside of VS Code), an editor will need to have the following installed locally:</p>
<ul>
<li>Node.js - <a>https://nodejs.org/en/download</a></li>
<li>Python - <a>https://www.python.org/downloads/</a></li>
<li>PIP - <a>https://pip.pypa.io/en/stable/installation/</a></li>
</ul>

<p>Once installed, it is recommended to keep up to date with the latest versions.</p>
</section>

<section id="sec-tooling-local-repo">
<h4>Repo setup</h4>
<p>Assuming the prerequisites listed in <a href="#sec-tooling-local-install"></a> are already installed, each time a new repo is cloned and work is to be started, the repo will need to be configured for its dependencies, based on the current <code>./package.json</code> file. </p>
<p>The command for this is:</p>
<pre>
npm install
</pre>

<p class="note">This command will update <code>./package-lock.json</code>, and can be run again if changes are made to <code>./package.json</code> for editing and/or updating dependencies based on the repo.</p>

<p>Once npm/Node is set up, it is also recommended to set up the requirements and further dependencies for validation to run properly.</p>

<p>The command for this is:</p>
<pre>
npm run prevalidate
</pre>

<p>This will check and (if needed) install the HTML 5 validator as noted in <a href="#sec-building"></a>. If the HTML 5 validator has already been installed, or the command has been run before (on another repo), the prompt will return:

<pre>
html5validator found. HTML validation ready.
</pre>

</section>

<section id="sec-tooling-local-validate">
<h4>Validation</h4>
<p>When creating a PR on GitHub, the tooling automatically performs a build process as noted in <a href="#sec-building"></a>, and part of that process is doing validation, both the internal to the tooling and for general HTML 5 validation.</p>

<p>While the internal tooling validation occurs at runtime while editing, waiting until the build action during a PR to check the HTML 5 validation can present an editor with unforseen issues (i.e. an invalid element or broken schema error), which then results in failures on the PR/build that must be fixed. Often times when this occurs the preview with redlines is not available in the PR, and/or the tooling will not allow a build to finish. Therefore it is highly recommended an editor runs the validation locally prior to pushing to GitHub to prevent these failures frmo occuring.</p>

<p>The command for this is:</p>
<pre>
npm run validate
</pre>

<p class="note">This command reports back errors in (2) seperate sections that are required to be resolved before a build can complete. The HTML validation includes line numbers for the convenience of the editor.</p>

<div id="ex-example-error" class="example"></div>

<pre>
> smpte-html-pub-tooling@2.1.0 prevalidate
> node scripts/ensure-html5validator.mjs

html5validator found. HTML validation ready.

> smpte-html-pub-tooling@2.1.0 validate
> run-p validate:doc validate:html

> smpte-html-pub-tooling@2.1.0 validate:html
> html5validator --errors-only ./doc/main.html

> smpte-html-pub-tooling@2.1.0 validate:doc
> node ./scripts/validate.mjs ./doc/main.html

Unknown element in clause HTMLElement {
[Symbol(SameObject caches)]: [Object: null prototype] { children: HTMLCollection {} }
}
".../SMPTE/html-pub/./doc/main.html":1512.7-1512.10: error: No "p" element in scope but a "p" end tag seen.
".../SMPTE/html-pub/./doc/main.html":1524.7-1524.10: error: No "p" element in scope but a "p" end tag seen.
".../SMPTE/html-pub/./doc/main.html":1554.21-1555.7: error: Saw "&lt;" when expecting an attribute name. Probable cause: Missing ">" immediately before.
".../SMPTE/html-pub/./doc/main.html":1554.21-1555.9: error: End tag had attributes.
".../SMPTE/html-pub/./doc/main.html":1555.242-1555.245: error: No "p" element in scope but a "p" end tag seen.
ERROR: "validate:html" exited with 5.
</pre>

</section>
</section>
</section>

<section class="annex informative" id="sec-table-examples">
Expand Down
Loading