google / docsy

A set of Hugo doc templates for launching open source content.
https://docsy.dev
Apache License 2.0
2.55k stars 889 forks source link

Support easy disabling of Docsy styles for HTML elements #1431

Open chalin opened 1 year ago

chalin commented 1 year ago

Docsy defaults are good most of the time, but now and again it would be convenient if they could be easily disabled. For example, consider the following excerpt from https://github.com/google/docsy/blob/main/assets/scss/_content.scss:

.td-content {
    // ...
    table {
        @extend .table-striped;
        @extend .table-responsive;
        @extend .table;
    }
    // ...
}

To disable, we could use a special class named, say, td-initial to be used like this:

.td-content {
    // ...
    table:not(.td-initial) {
        @extend .table-striped;
        @extend .table-responsive;
        @extend .table;
    }
    // ...
}

In markdown, one could now write something like this to recover the base styles of one specific table:

| Element     | Attribute   |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |
{.td-initial}

provided markdown attributes are enabled for blocks.

Thoughts @LisaFC et al.? I've come across the need for this and implemented it elsewhere -- see https://github.com/open-telemetry/opentelemetry.io/pull/2359.

Tasks:

Related:

emckean commented 1 year ago

+1 for this, it means (I think) that people will find it easier to keep in sync w/Docsy if they can just disable the styles they don't want rather than having to reapply patches?

chalin commented 1 year ago

Yes, that in particular.