Re: Weekend Project: ReSpec GitHub Pages

Adding yet another option to the mix. I tried out the above template but
found I still prefer bikeshed because I can more consistently use markdown
(i.e. the respec-github... template didn't seem to support markdown lists
and similar markdown input).

Running bikeshed locally is a pain, and I realized there's now an official
w3c github action called spec-prod <https://github.com/w3c/spec-prod> that
supports bikeshed and more. From the docs:
- Build ReSpec and Bikeshed specs.
- Validate generated document's markup and check for broken hyperlinks.

So I tested it out by creating the repo markdown-to-spec
<https://github.com/w3c-ccg/markdown-to-spec>, which uses the above github
action and includes the CCG boilerplate files. I made this into a template
repo so chairs can use this as an option if the work item owners want to
use markdown/bikeshed.

This is part of a larger CCG effort to add more accessible options for work
item owners that aren't as comfortable with html, etc. There are caveats as
to when you should/shouldn't use bikeshed (or other html generation tools).
I've started capturing this info/guidance in the CCG docs
<https://w3c-ccg.github.io/specs.html>. I encourage any feedback in the
form of issues or PRs against that repo. All of those files are generated
from markdown in the CCG site repo
<https://github.com/w3c-ccg/w3c-ccg.github.io)>.


<https://github.com/w3c-ccg/markdown-to-spec>

On Sun, Sep 20, 2020 at 4:57 PM Kim Hamilton <kimdhamilton@gmail.com> wrote:

> wherever it lives -- and Wayne and I can play with this first -- we should
> probably add this template as a starting point option* when creating future
> work items. It would probably be desired in almost all cases...
>
> *Not that Orie writes bugs. But if there are bugs, I imagine the chairs
> would be incentivized to accept that risk and help fix them, since it will
> boost collective productivity.
>
>
> On Sun, Sep 20, 2020 at 4:48 PM Kim Hamilton <kimdhamilton@gmail.com>
> wrote:
>
>> Orie, this is incredible, and great timing as well, as we're looking to
>> make it easier for people to create CCG artifacts. I will happily
>> help maintain this, and we can adopt it as a ccg repo if you'd like.
>>
>> As usual, your weekend coding projects put my weekend "code-ling"
>> projects to shame. If I wait long enough, you always eventually write the
>> code I need...
>>
>> On Sun, Sep 20, 2020 at 4:40 PM Orie Steele <orie@transmute.industries>
>> wrote:
>>
>>> Made a GitHub Template repository that makes technical specification
>>> development with ReSpec even easier:
>>>
>>> https://github.com/transmute-industries/respec-github-pages
>>>
>>> New Features
>>>
>>> - Support for GitHub Markdown and HTML
>>> - Automatic SEO / feed / sitemap support in XML (including schema.org /
>>> jsonld)
>>> - Guidance for hosting JSON files alongside spec text.
>>> - Support for multiple versions that can share the same configuration
>>> files
>>> - Support for multiple Specs that can share the same configuration files
>>> - Relies on GitHub Pages, so documentation for "how to do things" is
>>> already provided by them.
>>> - No need to "build the spec" like is needed with bikeshed, github does
>>> this for you, and automatically notifies you when it's done (no workflows
>>> or CI needed).
>>>
>>> Dependencies
>>>
>>> Just uses ReSpec and GitHub.... so there is no "source code"... it's
>>> just a configuration of free existing tooling.
>>>
>>> If you really need to, you can edit 100% of the source files in the
>>> github repo, just like you had to before...
>>> If you don't need to configure ReSpec, you don't need to even see it,
>>> and you can use markdown to quickly sketch your spec up.
>>>
>>> I opened an issue on respec, trying to find a better home for the repo /
>>> template.
>>>
>>> Not sure where it belongs, but hopefully some other github organization
>>> with more maintainers : )
>>>
>>> OS
>>>
>>> --
>>> *ORIE STEELE*
>>> Chief Technical Officer
>>> www.transmute.industries
>>>
>>> <https://www.transmute.industries>
>>>
>>