Improve the proposal repo layout. #7
Conversation
- Change from `.wit.md` files with
wit-embedded-in-markdown-code-comments to just `.wit` files
containing just Wit. Feedback from early users so far has been that
people want to just maintain plain wit.
- Use the new `--html-in-md` option to generate the prettier HTML
output in the `.md` file, which is rendered on Github. The specifics
here may evolve, but overall the idea is:
- Don't check in `.html` files into the repo, as they can't be
rendered and as such are confusing.
- Do check in a generated `.md` file, with as much formatting and
linkifying as we can get.
The generated HTML has a *lot* of room for improvement. But at least with this
PR the HTML is viewable from the Github UI and it has a table of contents and
the formatting is a little tidier.
sunfishcode
force-pushed
the
sunfishcode/prettier
branch
from
f9457f6 to
8cfab13
Compare
|
Oh interesting, so we are moving away from the wit-embedded-in-md thing. I'm fine with that. And we have a tool that will convert wit to wit-embedded-in-md? If this PR supposed to contain that output of that tool? I don't think I'm seeing it? I do see what looks like regular html in wasi-proposal-template.md.. is that supposed to be the wit-in-md instead? |
|
No, I don't have a tool to convert The regular HTML in the wasi-proposal-template.md is there because Github will render HTML when it's in a |
|
I see, so just to be clear, once this transition is made there will be no more There will just be |
|
The wit tooling will still recognize and process And if someone wants to make the case that |
|
With this PR, yes, the template repo will just have |
|
I'm a little concerned about having html files with the .md extension. Seems unfortunate to have to do that. Could we not find a solution where a github action publishes the html to github pages using the wit-to-html tool, and then we could avoid checking the html at all? I believe this is out the wasm core spec proposals public their html isn't it? The top of the README for each proposal could then link directly to github pages? My intent here is not to block this PR, just discuss that optiamal end point that we might want to get to/ |
I'd be overjoyed to review a PR for that. |
|
I personally do not know how to set up an upload-to-github pages pipeline. If someone would like to see this happen, I'd greatly appreciate it if they could step up and make it happen. I'll happily replace everything I'm doing here with it. |
|
For the record, I also don't know how to write an HTML generator that generates nice-looking HTML. |
sbc100
left a comment
sbc100
left a comment
There was a problem hiding this comment.
lgtm
BTW, I don't see --html-in-md anywhere in the PR, is that because you are running by hand rather than in the github action?
|
The --html-in-md is in the wit-abi-up-to-date action. |
Add an example dependency using a `deps` directory. And rename some things for clarity.
This updates to the 0.3.0 release of wit-bindgen.
|
I've now added a deps directory example, inspired by this wasi-http PR, and updated this to use the latest wit-bindgen. I've also spoken offline with folks I know that like the .wit.md format and they agreed going with plain .wit for now makes sense. This is likely not the last word, however until we have more tooling in place, this is a simple thing that works for now. |
2 participants
Change from
.wit.mdfiles with wit-embedded-in-markdown-code-comments to just.witfiles containing just Wit. Feedback from early users so far has been that people want to just maintain plain wit.Use the new
--html-in-mdoption to generate the prettier HTML output in the.mdfile, which is rendered on Github. The specifics here may evolve, but overall the idea is:.htmlfiles into the repo, as they can't be rendered and as such are confusing..mdfile, with as much formatting and linkifying as we can get.The generated HTML has a lot of room for improvement. But at least with this PR the HTML is viewable from the Github UI and it has a table of contents and the formatting is a little tidier.