Docs improvements: content in Markdown, organization into subtemplates, fixed tests #4401
Conversation
…int in separate .css files and their separate HTTP requests
…ve-docs # Conflicts: # documentation/index.html
…quickly that there’s no need to pre-render them and save the intermediate .js files
…at we can add in logic to include different files for v1 versus v2
…apse the parts of `releaseHeader` into one compact function
lydell
left a comment
There was a problem hiding this comment.
I like this. Very much. Very well done!
| </b> | ||
| """ | ||
| htmlFor = -> | ||
| marked = require 'marked' |
There was a problem hiding this comment.
This needs to be added to package.json,
There was a problem hiding this comment.
Done. Are you okay with me merging this into develop whenever I'm done testing it? I'm working on getting the 2 docs built in their branch, based on this.
There was a problem hiding this comment.
Master, I mean.
|
|
||
| All together now: | ||
|
|
||
| <table class="definitions"> |
There was a problem hiding this comment.
If we use CommonMark, then we could possibly write the tables in a more readable way. http://spec.commonmark.org/0.27/#html-blocks
What do you think?
There was a problem hiding this comment.
Is that supported by the marked module? Its docs say to use this syntax: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#tables
I just haven't gotten around to converting, the automated HTML-to-Markdown converters I tried didn't support tables.
There was a problem hiding this comment.
Ah, I didn't realize you used an autmated converter.
- marked does not implement the CommonMark spec. Use CommonMark instead of loosely defined Markdown flavour markedjs/marked#563
- Yes, there are "unofficial" markdown extensions that allow you to type tables as ASCII tables and have that converted to HTML. That would be nice, too, but what I was talking about is that CommonMark supports having entire block of HTML without having to have all those blank lines and missing indentation: http://spec.commonmark.org/0.27/#example-115
There was a problem hiding this comment.
Isn't that essentially treating the table as one big passthrough? But we still want markdown within the cells to be evaluated.
I would think the github style would be more idiomatic markdown than any form of HTML tags. It'll just take manual effort to convert.
There was a problem hiding this comment.
There’s also the issue of rendering a headerless table in Markdown: markedjs/marked#484
There was a problem hiding this comment.
I think we only have two tables in total currently, so the way it is currently is not such a big deal. But if it could be made nicer in any way, that'd be great! 👍
There was a problem hiding this comment.
I think that can be a future improvement. You're welcome to try 😄
This reverts commit ec9e559.
d2b1ee7 to
16dda9c
Compare
16dda9c to
4aa0130
Compare
…auto-generated and conflicting ids
|
Very, very nice! |
|
Then it will cost less time to translate into Chinese. Great. |
… docs can have different example code blocks/editors
59001f2 to
85b3be9
Compare
…keywords and triple backticks (docs output is unchanged)
…s, fixed tests (jashkenas#4401) * Replace tiny bitmaps with base64-encoded URIs * Optimize SVGs; replace logo PNG with SVG * Modernize favicon * Embed CSS; a bit unorthodox, but we’re a single page so there’s no point in separate .css files and their separate HTTP requests * Documentation is now markdown, converted to HTML on compilation * Render the examples when we’re rendering index.html; they compile so quickly that there’s no need to pre-render them and save the intermediate .js files * Split apart index.html into components that Cakefile assembles, so that we can add in logic to include different files for v1 versus v2 * Split building index.html and building test.html into two tasks; collapse the parts of `releaseHeader` into one compact function * Move include logic into templates * Get error messages tests to work in the browser * Update output index.html * Split body into nav and body * Watch subtemplates * Revert "Split body into nav and body" This reverts commit ec9e559. * Add marked * Update gitignore * Use idiomatic markdown output for code blocks (<pre><code>) * Handle ids within the template, not in the Cakefile; remove marked’s auto-generated and conflicting ids * Move the `codeFor` function into versioned folders, so that v1 and v2 docs can have different example code blocks/editors * Update packages, including new highlight.js which supports our newer keywords and triple backticks (docs output is unchanged)
More improvements to the documentation:
index.htmlnow requires sub-templates, to divide content into relevant sub-files. The build process reassembles everything. The sub-files are mostly inside adocumentation/v1folder, giving the 2 docs source files a logical place to go.index.htmlandtest.htmlare now built via separatecaketasks, to avoid a gigantic function.test.htmlnow run all the tests, includingerror_messages.coffee, thanks to a fixed polyfill for@throw.