improve AsciiDoc CSS #770

Open
opened 1 month ago by tastytea · 4 comments

I usually use AsciiDoc for “readme”s, but the styling could be improved. It looks like Gitea doesn't want to support AsciiDoc, so i didn't open an issue there.

Admonition blocks

Admonition blocks are visually distinct text blocks, used to draw attention. They can have the following labels: NOTE, TIP, IMPORTANT, CAUTION, WARNING.

Currently they look like this: screenshot admonition block

It would be nice to have them stand out more. AsciiDoctor converts them to HTML like this:

<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This is a note
</td>
</tr>
</table>
</div>

To be able to style them, the sanitizer would have to be configured to allow the class attribute on the relevant elements.

[markup.sanitizer]
ELEMENT = div
ALLOW_ATTR = class

and so on.

Example CSS
/* remove borders */
div.asciidoc:not(code) div.admonitionblock table * {
     border: 0 !important;
}
/* bigger label, grey bar between label and text */
div.asciidoc:not(code) div.admonitionblock td.icon {
    font-size: 120%;
    font-weight: bold;
    border-right: 0.2em solid grey !important;
}
/* colon after label */
div.asciidoc:not(code) div.admonitionblock td.icon div.title::after {
    content: ":";
}
/* make warning label red */
div.asciidoc:not(code) div.warning td.icon {
    color: #c33;
}

That would look something like this: screenshot admonition block

Code blocks

They don't have syntax highlighting. I don't know how to fix that.

Image positioning

image::foo.png[role="right"] is translated to <div class="imageblock right"><img… in Asciidoctor. The expected result can be achieved with this CSS snippet:

div.asciidoc:not(code) div.left img {
    float: left;
}
div.asciidoc:not(code) div.right img {
    float: right;
}

Miscellaneous

Not sure if these are all that useful for a code forge… I have them in another Gitea instance but i think i never used them. 😄

Example CSS
/* tables that are requested to have no frame / grid */
div.asciidoc:not(code) table.frame-none {
    border: 0;
}
div.asciidoc:not(code) table.grid-none * {
    border: 0;
}

/* elements that are requested to be aligned specially */
div.asciidoc:not(code) .halign-left {
    text-align: left;
}
div.asciidoc:not(code) .halign-center {
    text-align: center;
}
div.asciidoc:not(code) .halign-right {
    text-align: right;
}

I usually use AsciiDoc for “readme”s, but the styling could be improved. It looks like Gitea doesn't want to support AsciiDoc, so i didn't open an issue there. ### Admonition blocks [Admonition blocks](https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/) are visually distinct text blocks, used to draw attention. They can have the following labels: NOTE, TIP, IMPORTANT, CAUTION, WARNING. Currently they look like this: ![screenshot admonition block](/attachments/70e8bc9a-95f0-4398-aedb-47724dfd096b) It would be nice to have them stand out more. AsciiDoctor converts them to HTML like this: ```html <div class="admonitionblock note"> <table> <tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content"> This is a note </td> </tr> </table> </div> ``` To be able to style them, the sanitizer would have to be configured to allow the `class` attribute on the relevant elements. ```ini [markup.sanitizer] ELEMENT = div ALLOW_ATTR = class ``` and so on. <details><summary>Example CSS</summary> ```css /* remove borders */ div.asciidoc:not(code) div.admonitionblock table * { border: 0 !important; } /* bigger label, grey bar between label and text */ div.asciidoc:not(code) div.admonitionblock td.icon { font-size: 120%; font-weight: bold; border-right: 0.2em solid grey !important; } /* colon after label */ div.asciidoc:not(code) div.admonitionblock td.icon div.title::after { content: ":"; } /* make warning label red */ div.asciidoc:not(code) div.warning td.icon { color: #c33; } ``` That would look something like this: ![screenshot admonition block](/attachments/81c3f942-b148-4070-8e1f-c87b941cbb8d) </details> ### Code blocks They don't have syntax highlighting. I don't know how to fix that. ### Image positioning `image::foo.png[role="right"]` is translated to `<div class="imageblock right"><img…` in Asciidoctor. The expected result can be achieved with this CSS snippet: ```css div.asciidoc:not(code) div.left img { float: left; } div.asciidoc:not(code) div.right img { float: right; } ``` ### Miscellaneous Not sure if these are all that useful for a code forge… I have them in another Gitea instance but i think i never used them. 😄 <details> <summary>Example CSS</summary> ```css /* tables that are requested to have no frame / grid */ div.asciidoc:not(code) table.frame-none { border: 0; } div.asciidoc:not(code) table.grid-none * { border: 0; } /* elements that are requested to be aligned specially */ div.asciidoc:not(code) .halign-left { text-align: left; } div.asciidoc:not(code) .halign-center { text-align: center; } div.asciidoc:not(code) .halign-right { text-align: right; } ``` </details>
Owner

Asciidoc support is not officially supported with Gitea, for Codeberg we provide it using the following config: https://codeberg.org/Codeberg-Infrastructure/build-deploy-gitea/src/branch/codeberg-1.17/etc/gitea/conf/app.ini#L183

Contributions very welcome, but always keep in mind that we need to ensure the security of our users.

Asciidoc support is not officially supported with Gitea, for Codeberg we provide it using the following config: https://codeberg.org/Codeberg-Infrastructure/build-deploy-gitea/src/branch/codeberg-1.17/etc/gitea/conf/app.ini#L183 Contributions very welcome, but always keep in mind that we need to ensure the security of our users.
rwa added the
Codeberg
contribution welcome
labels 1 month ago
Collaborator

We likely want to add a custom policy here.

Is there a list of classes that are used by AsciiDoc?

We likely want to add a custom policy [here](https://codeberg.org/Codeberg/gitea/src/commit/295ca80c0231e9d553203d0ae857297c5fd200b1/modules/markup/sanitizer.go#L52). Is there a list of classes that are used by AsciiDoc?
Poster

Contributions very welcome, but always keep in mind that we need to ensure the security of our users.

I was planning on making a PR, i just wanted to gather some feedback first. 😊

Where would i make CSS changes? /etc/gitea/public/codeberg.css seems to be suitable, with prefers-color-scheme conditionals. Or should i change the themes (where can i find them?)?

Is there a list of classes that are used by AsciiDoc?

It doesn't look like it. However, there is a demo page for “skins” where the class names can be extracted from.¹

But, can't we just allow any class on certain HTML elements?

¹ curl -s https://darshandsoni.com/asciidoctor-skins/ | grep -Po 'class="[^"]+"'

> Contributions very welcome, but always keep in mind that we need to ensure the security of our users. I was planning on making a PR, i just wanted to gather some feedback first. 😊 Where would i make CSS changes? [/etc/gitea/public/codeberg.css](https://codeberg.org/Codeberg-Infrastructure/build-deploy-gitea/src/branch/codeberg-1.17/etc/gitea/public/codeberg.css) seems to be suitable, with `prefers-color-scheme` conditionals. Or should i change the themes (where can i find them?)? > Is there a list of classes that are used by AsciiDoc? It doesn't look like it. However, there is a [demo page for “skins”](https://darshandsoni.com/asciidoctor-skins/) where the class names can be extracted from.¹ But, can't we just allow any class on certain HTML elements? ¹ `curl -s https://darshandsoni.com/asciidoctor-skins/ | grep -Po 'class="[^"]+"'`
Collaborator

I was planning on making a PR, i just wanted to gather some feedback first. 😊

👍

Where would i make CSS changes? /etc/gitea/public/codeberg.css seems to be suitable, with prefers-color-scheme conditionals. Or should i change the themes (where can i find them?)?

Yeah that's possible, but I think we should prefer them in https://codeberg.org/Codeberg/gitea/src/branch/codeberg-1.17/web_src/less/markup/content.less.

But, can't we just allow any class on certain HTML elements?

Certain classes can trigger code to be run, which is quite dangerous. The allowance should be quite conservative 😅. We can start with the classes you can find and add more if there are more classes that turns out to be rendered.

> I was planning on making a PR, i just wanted to gather some feedback first. 😊 👍 > Where would i make CSS changes? /etc/gitea/public/codeberg.css seems to be suitable, with prefers-color-scheme conditionals. Or should i change the themes (where can i find them?)? Yeah that's possible, but I think we should prefer them in https://codeberg.org/Codeberg/gitea/src/branch/codeberg-1.17/web_src/less/markup/content.less. > But, can't we just allow any class on certain HTML elements? Certain classes can trigger code to be run, which is quite dangerous. The allowance should be quite conservative 😅. We can start with the classes you can find and add more if there are more classes that turns out to be rendered.
tastytea referenced this issue from a commit 4 weeks ago
tastytea referenced this issue from a commit 3 weeks ago
tastytea referenced this issue from a commit 3 weeks ago
tastytea referenced this issue from a commit 3 weeks ago
Sign in to join this conversation.
No Milestone
No Assignees
3 Participants
Notifications
Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Codeberg/Community#770
Loading…
There is no content yet.