separate Markdown syntax from style guidance; streamline style guide #20170
Conversation
…nce and remove redundancies
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
Files changed:
|
taroface
force-pushed
the
style-guide-refactor
branch
from
ecbde50 to
c3a791c
Compare
| ~~~markdown | ||
| [Link text](https://example.com) | ||
| ~~~ | ||
| If the page is versioned, use `{{ page.version.version }}` rather than the hardcoded version. Exceptions apply when linking to versioned pages from [non-versioned pages](#links-to-versioned-docs-pages-from-a-non-versioned-directory) and [technical advisory pages](#links-to-cockroachdb-docs-from-technical-advisories). |
There was a problem hiding this comment.
I think this is probably fine, but for me it opens up a can of worms around why we version some pages and not others, and if the designation changes.
There was a problem hiding this comment.
All docs pertaining to the CRDB binary are versioned. Docs for CockroachDB Cloud and MOLT aren't versioned because they're not beholden to the CRDB versioning. So it's a structural decision that reflects the product rather than a subjective one, IMO. Let me know if it seems worth spelling this out in the style guide, though.
| #### HTML | ||
|
|
||
| If it's necessary to include more complex table formatting or if a [Markdown table](#markdown) becomes too unwieldy, create a table using HTML. This formatting is not recommended unless necessary, since it is hard for other writers to parse and maintain. | ||
| ## Content elements |
There was a problem hiding this comment.
i feel like the link at the top of this doc pointing folks to the markdown guide makes keeping this section around unnecessary
PS I absolutely love this PR, thank you for writing it
There was a problem hiding this comment.
I realized that a lot more content should go in the Markdown Guide, so i moved this and more stuff over there!
|
|
||
| Use tables to display structured information in an easy-to-read format. We use two types of tables: [Markdown](#markdown-tables) and [HTML](#html-tables). | ||
|
|
||
| ### Markdown tables |
There was a problem hiding this comment.
somewhere in this section, you may want to include the alignment guidance mentioned in this slack thread
Co-authored-by: Florence Morris <[email protected]>
Co-authored-by: Florence Morris <[email protected]>
Relates to DOC-14618
MarkdownGuide.md