Spec markdoen build refactor

[jdesrosiers]

After talking with @gregsdennis about some of the shortcomings of the build system, I looked into what improvements I could make and fell down a bit of a rabbit hole. I found that there's a Remark language server and VSCode extension that we can use to get linting in our editors while writing! I had to define the build in a little different way to make it compatible with those tools. I also broke the build down into three parts to facilitate the different actions that need to run on spec markdown files.

• spec -- Configures custom markdown features
• lint -- Configures linting rules
• build -- Converts markdown to HTML

So we an use spec+lint for linting and spec+build for generating HTML. Later, if we want, we can add a "github" configuration and use github+lint to lint Github markdown files with the same linting rules we use for the spec. The main reason I didn't do that yet is because of all the changes that would be needed to get the Github markdown to pass the linter. I'd rather do that separately.

Some other things to know:

• The lint command now lints both javascript and markdown instead of just javascript.
• The build and build-all commands now don't lint, they just build.
• Building doesn't preserve the directory structure any more. Everything ends up flattened to the "web" folder. I couldn't find a reasonable solution that preserves the directory structure.
• The spec files were moved into the specs folder. This allows us to separate spec markdown files from the Github markdown. This is good practice anyway, but it's necessary in this case because the spec markdown is effectively its own flavor of markdown due to our customizations and needs to be handled differently from Github markdown.
• For some reason, the new build setup catches more issues than the old one, so there are some markdown fixes in addition to the build changes.
• The link checker caught an interesting issue. The propertyDependencies proposal links to the spec. In order for that link to work once built, it needs to point to live version on the website (html), which doesn't exist yet. But, if it points to the website, it might not take into account anchor changes in the document and think a link is invalid when it's not. (I hope that explanation sort of made sense.) I think the solution is to make the links point to the markdown version and then add a build processing step that rewrites links to where they will be published. Then the links work when built and the link checker can do its job. For now, I'm leaving the link pointing to the markdown file because it's the only solution that doesn't involve disabling the link checker entirely, but this needs a real solution at some point.
• You can use <!-- lint ignore rule-name --> to ignore a rule on a block or <!-- lint disable rule-name --> and <!-- lint enable rule-name --> to ignore a rule within those comments. I used this a couple times for really long headings instead of globally disabling the rule.

[jdesrosiers]

@gregsdennis It occurred to me that since we have all the specs in one place now, the build-all task isn't really necessary anymore. It was useful before because we had to specify multiple paths in order to get everything and it was easy to miss something. Now that we can just do, npm run build -- specs, I don't think we really need two build tasks. So, I removed build-all in favor of build -- specs. Let me know if you'd rather keep build-all. If so, I can restore it.

[gregsdennis]

The output spec is still in /ouptut. Do you want to move it into the folder with the others?

[jdesrosiers]

The output spec is still in /ouptut. Do you want to move it into the folder with the others?

The output spec was moved like the rest of the spec files. It's in /specs/output now. I think that's the right place for it.

[gregsdennis]

Just the one thing. Otherwise ✔️

[gregsdennis]

✔️
Discussed merging early offline.