Recent Commits to styleguide:gh-pages (46)

drop html supplemental files

Now that all html guides have converted to markdown, we don't need
these JS or CSS files anymore.  Punt them.

cpp: migrate to markdown

Automated export from internal guides

PiperOrigin-RevId: 1010850167

Automated export from internal guides

PiperOrigin-RevId: 1010509341

typescript: migrate to markdown

This also contains some internal changes that weren't exported previously.

Automated export from internal guides

PiperOrigin-RevId: 1009345184

Automated export from internal guides

PiperOrigin-RevId: 1009174118

Automated export from internal guides

PiperOrigin-RevId: 1009140818

java: migrate to markdown

tcltk: link in external guide we use

We don't have one ourselves, but we refer to this one.

README: add a VCS section explicitly

README: unify the style guide lists into one

We're already mixing sources in the main list of guides, and having
a separate list isn't really helping that much.  Merge into one list
and call out provenance when reporting issues.

README: fold XML back into the main list

The longer explanation isn't really necessary here, and the details
are contained in the XML guide itself.  Other guides sometimes have
advice beyond purely formatting.

js: explain the rectangle rule

The function argument examples say one layout "violates the rectangle
rule" without saying what that is.  Add a short definition and link to
the full description in the google-java-format wiki.

js: link to a definition of CSP

"CSP environments" is not explained.  Spell out Content Security Policy
and link to a description of it.

Automated export from internal guides

PiperOrigin-RevId: 1007354033

Automated export from internal guides

PiperOrigin-RevId: 1006046694

Automated export from internal guides

PiperOrigin-RevId: 1005823146

Automated export from internal guides

PiperOrigin-RevId: 1005639216

Automated export from internal guides

PiperOrigin-RevId: 1005568362

Automated export from internal guides

PiperOrigin-RevId: 1004267654

Automated export from internal guides

PiperOrigin-RevId: 1004098447

link in new Rust guide #276

Fixes: #276

Automated export from internal guides

PiperOrigin-RevId: 1004009482

docguide: switch to autotoc

This lets GH pages generate the TOC for us.

docguide: run files through mdformat

This is to prepare for automatic export and make diffs easier to review.

Automated export from internal guides

PiperOrigin-RevId: 1003227363

Automated export from internal guides

PiperOrigin-RevId: 1002394198

README: add an editor section

Some guides touch on editors & tools, but many don't.
Start a section to cover these projects.

docguide: remove unused VERSION file

README: create a dedicated licensing section

Clarify/document the difference between written guides & code.

Automated export from internal guides

PiperOrigin-RevId: 1001469701

Automated export from internal guides

PiperOrigin-RevId: 1001293847

Automated export from internal guides

PiperOrigin-RevId: 1001270344

Automated export from internal guides

PiperOrigin-RevId: 1001096816

Automated export from internal guides

PiperOrigin-RevId: 1000931729

verilog: wrap `define in code span to fix Kramdown table parsing

Kramdown's table row validator only runs its :codespan and :span_html parsers (not :escaped_chars), so the backslash-escaped backtick in [\`define macros](#defines) opened an unclosed code span across the row's | delimiter and caused Kramdown to abort parsing the table. Wrap `define in a two-backtick inline code span so Kramdown renders the table, and drop the duplicate #sequential-logic anchor above #sequential-logic-registers.

C#, R: sync latest internal to add autotoc & good/bad code style

lisp, vim: sync latest internal to add autotoc

enable block html parsing for zippies

This doesn't directly support zippies, but it's needed in cases where
guides use <div> blocks as the first zippy element.  For now, it should
be a noop.

This resyncs the vim guide to the latest (with most zippies removed)
and replaces the manual Python TOC with an automatic one like most of
the other guides.

verilog: fix naming-overview table and colliding heading anchors

Convert the Hoedown multiline naming-overview table into a standard single-line Markdown table so Kramdown renders it as an HTML table instead of a definition list. Disambiguate colliding heading anchors and wrap macro references in inline code spans.

python: sync latest version

This includes good/bad code updates.

verilog: use verilog code fence tag for Rouge highlighting

Rouge on GitHub Pages only registers its SystemVerilog lexer under 'verilog' and does not recognize 'systemverilog', causing Kramdown to emit bare <pre><code> blocks without syntax or Good/Bad highlighting.

Workaround for #1050

js: migrate to markdown

Since the guide is frozen and is seeing no more internal updates,
might as well convert it to markdown to drop HTML/CSS deps.

htmlcss: migrate to markdown

add support for automatic TOC

This is a port of the existing styleguide.js auto TOC logic from the
HTML guides to the newer markdown guides.  Rather than generate the
entire TOC in JS, rely on GH's generator to create, and then process
it slightly with minimal CSS+JS.

While GH's builtin markdown renderer automatically creates sidepanel
TOCs, the GH pages export does not.  Use the `* TOC {:toc}` form so
the export automatically generates for us.  The downside is that it
also shows up in GH's builtin markdown renderer, but it's only one
line at the top, so it shouldn't be onerous.

The CSS logic tweaks which levels are displayed in the generated
TOC: we hide the single top-level, and omit levels deeper than 2.
The JS logic puts the TOC into a <details> HTML element (internally
called a zippy) so that it's collapsed by default.

While the old auto TOC codebase supported "horizontal" and "vertical"
formats, the new one only supports "vertical".  Most of our guides do
not care and take the default since that's what internal & external
markdown renderers use, but notably some are using horizontal still:
* C++, HTML/CSS, Java, JS, TS: external, but not internal
* shell: internal & external (via manual TOC)

We'll leave the shell guide alone, but the rest will be switched over
in the future as we regenerate things, and discuss with respective
maintainers.