Create new admonition boxes (#337)
Related issue: https://codeberg.org/Codeberg/Documentation/issues/330 This is my attempt at adding admonition-like boxes to the documentation. The goal is to make important stuff stand out more (especially warnings and alike). The system uses a custom `<admonition>` box which allows classes for further customization. I.e. `<admonition class="warning">` to display a warning box. I first wanted to make individual boxes (`<warning>`, `<note>`, ...) but decided against it, as it would've created a lot of duplicate CSS. The CSS is designed in such a way that the first paragraph of the box is made bold (font-weight 700) while any subsequent ones are not. The following forms of admonitions are included: - Info (default) - Note - Tip - Warning Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/337 Co-authored-by: Andre601 <github@andre601.ch> Co-committed-by: Andre601 <github@andre601.ch>
This commit is contained in:
Andre601
Panagiotis "Ivory" Vasilopoulos
parent
536884cd59
commit
b234b71bb7
7 changed files with 181 additions and 13 deletions
19
.eleventy.js
19
.eleventy.js
|
|
@ -40,6 +40,25 @@ module.exports = function(eleventyConfig) {
|
|||
.use(markdownItAnchor, mdAnchorOpts)
|
||||
)
|
||||
|
||||
eleventyConfig.addPairedShortcode("admonition", function(content, type, title) {
|
||||
let titleStr = "";
|
||||
if(title) {
|
||||
titleStr = title;
|
||||
} else if(type) {
|
||||
titleStr = type.substring(0, 1).toUpperCase() + type.substring(1).toLowerCase();
|
||||
} else {
|
||||
titleStr = "Info";
|
||||
}
|
||||
|
||||
return `<div class="admonition${type ? ` ${type.toLowerCase()}` : ""}">
|
||||
<div class="admonition-title">
|
||||
<span class="admonition-icon${type ? ` ${type.toLowerCase()}` : ""}"></span>
|
||||
${titleStr}
|
||||
</div>
|
||||
<div class="admonition-content">${content}</div>
|
||||
</div>`
|
||||
});
|
||||
|
||||
return {
|
||||
dir: {
|
||||
input: "content"
|
||||
|
|
|
|||
|
|
@ -1,3 +1,25 @@
|
|||
:root{
|
||||
--admonition-background-color--info: rgba(68, 138, 255, 0.2);
|
||||
--admonition-background-color--note: rgba(0, 184, 212, 0.2);
|
||||
--admonition-background-color--warning: rgba(255, 145, 0, 0.2);
|
||||
--admonition-background-color--tip: rgba(0, 191, 165, 0.2);
|
||||
--admonition-background-color--question: rgba(100, 221, 23, 0.2);
|
||||
|
||||
--admonition-border-color--info: rgb(68, 138, 255);
|
||||
--admonition-border-color--note: rgb(0, 184, 212);
|
||||
--admonition-border-color--warning: rgb(255, 145, 0);
|
||||
--admonition-border-color--tip: rgb(0, 191, 165);
|
||||
--admonition-border-color--question: rgb(100, 221, 23);
|
||||
|
||||
--admonition-icon--info: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M13 7.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0Zm-3 3.75a.75.75 0 0 1 .75-.75h1.5a.75.75 0 0 1 .75.75v4.25h.75a.75.75 0 0 1 0 1.5h-3a.75.75 0 0 1 0-1.5h.75V12h-.75a.75.75 0 0 1-.75-.75Z"></path><path d="M12 1c6.075 0 11 4.925 11 11s-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1ZM2.5 12a9.5 9.5 0 0 0 9.5 9.5 9.5 9.5 0 0 0 9.5-9.5A9.5 9.5 0 0 0 12 2.5 9.5 9.5 0 0 0 2.5 12Z"></path></svg>');
|
||||
--admonition-icon--note: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M17.263 2.177a1.75 1.75 0 0 1 2.474 0l2.586 2.586a1.75 1.75 0 0 1 0 2.474L19.53 10.03l-.012.013L8.69 20.378a1.753 1.753 0 0 1-.699.409l-5.523 1.68a.748.748 0 0 1-.747-.188.748.748 0 0 1-.188-.747l1.673-5.5a1.75 1.75 0 0 1 .466-.756L14.476 4.963ZM4.708 16.361a.26.26 0 0 0-.067.108l-1.264 4.154 4.177-1.271a.253.253 0 0 0 .1-.059l10.273-9.806-2.94-2.939-10.279 9.813ZM19 8.44l2.263-2.262a.25.25 0 0 0 0-.354l-2.586-2.586a.25.25 0 0 0-.354 0L16.061 5.5Z"></path></svg>');
|
||||
--admonition-icon--warning: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M13 17.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0Zm-.25-8.25a.75.75 0 0 0-1.5 0v4.5a.75.75 0 0 0 1.5 0v-4.5Z"></path><path d="M9.836 3.244c.963-1.665 3.365-1.665 4.328 0l8.967 15.504c.963 1.667-.24 3.752-2.165 3.752H3.034c-1.926 0-3.128-2.085-2.165-3.752Zm3.03.751a1.002 1.002 0 0 0-1.732 0L2.168 19.499A1.002 1.002 0 0 0 3.034 21h17.932a1.002 1.002 0 0 0 .866-1.5L12.866 3.994Z"></path></svg>');
|
||||
--admonition-icon--tip: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M12.596 2.043c1.075.076 2.059.281 2.743.956.698.688.92 1.696.92 2.941 0 .432-.057.955-.117 1.438-.026.2-.051.392-.076.572l-.056.429h2.05c.752 0 1.446.108 2.036.404.612.306 1.062.787 1.355 1.431.551 1.214.542 3.008.223 5.394l-.051.39c-.134 1.01-.248 1.872-.396 2.58-.166.795-.394 1.496-.816 2.05-.89 1.168-2.395 1.372-4.583 1.372-2.331 0-4.08-.418-5.544-.824l-.602-.17c-1.023-.29-1.852-.526-2.69-.586A1.75 1.75 0 0 1 5.25 22h-1.5A1.75 1.75 0 0 1 2 20.25V9.75C2 8.784 2.784 8 3.75 8h1.5a1.75 1.75 0 0 1 1.746 1.633 1.85 1.85 0 0 0 .523-.131c.961-.415 2.774-1.534 2.774-4.2V4.249c0-1.22 1.002-2.298 2.303-2.206ZM7 18.918c1.059.064 2.079.355 3.118.652l.568.16c1.406.39 3.006.77 5.142.77 2.277 0 3.004-.274 3.39-.781.216-.283.388-.718.54-1.448.136-.65.242-1.45.379-2.477l.05-.384c.32-2.4.253-3.795-.102-4.575-.16-.352-.375-.568-.66-.711-.305-.153-.74-.245-1.365-.245h-2.37c-.681 0-1.293-.57-1.211-1.328.026-.243.065-.537.105-.834l.07-.527c.06-.482.105-.921.105-1.25 0-1.125-.213-1.617-.473-1.873-.275-.27-.774-.455-1.795-.528-.351-.024-.698.274-.698.71v1.053c0 3.55-2.488 5.063-3.68 5.577-.372.16-.754.232-1.113.26ZM3.75 20.5h1.5a.25.25 0 0 0 .25-.25V9.75a.25.25 0 0 0-.25-.25h-1.5a.25.25 0 0 0-.25.25v10.5c0 .138.112.25.25.25Z"></path></svg>');
|
||||
--admonition-icon--question: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M10.97 8.265a1.45 1.45 0 0 0-.487.57.75.75 0 0 1-1.341-.67c.2-.402.513-.826.997-1.148C10.627 6.69 11.244 6.5 12 6.5c.658 0 1.369.195 1.934.619a2.45 2.45 0 0 1 1.004 2.006c0 1.033-.513 1.72-1.027 2.215-.19.183-.399.358-.579.508l-.147.123a4.329 4.329 0 0 0-.435.409v1.37a.75.75 0 1 1-1.5 0v-1.473c0-.237.067-.504.247-.736.22-.28.486-.517.718-.714l.183-.153.001-.001c.172-.143.324-.27.47-.412.368-.355.569-.676.569-1.136a.953.953 0 0 0-.404-.806C12.766 8.118 12.384 8 12 8c-.494 0-.814.121-1.03.265ZM13 17a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path><path d="M12 1c6.075 0 11 4.925 11 11s-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1ZM2.5 12a9.5 9.5 0 0 0 9.5 9.5 9.5 9.5 0 0 0 9.5-9.5A9.5 9.5 0 0 0 12 2.5 9.5 9.5 0 0 0 2.5 12Z"></path></svg>');
|
||||
|
||||
--admonition-icon-dimension: 20px;
|
||||
}
|
||||
|
||||
.content :not(img, pre) { max-width: 80ch; }
|
||||
.content img { border: 5px solid rgba(0, 0, 0, 0.2); max-width: 100%; }
|
||||
.content blockquote { margin: 0; }
|
||||
|
|
@ -49,3 +71,94 @@ code:not(pre > code) {
|
|||
border-color: var(--dm-code-border-color);
|
||||
}
|
||||
|
||||
/* Custom Admonition boxes */
|
||||
|
||||
.admonition {
|
||||
background-color: var(--admonition-background-color--info);
|
||||
border: .2rem solid var(--admonition-border-color--info);
|
||||
border-radius: .3rem;
|
||||
|
||||
border-left-width: .5rem;
|
||||
|
||||
padding: 1em 1.5em;
|
||||
}
|
||||
|
||||
.admonition-title {
|
||||
font-weight: bold;
|
||||
font-size: 1.2em;
|
||||
}
|
||||
|
||||
.admonition-icon::before {
|
||||
content: "";
|
||||
|
||||
background-color: var(--admonition-border-color--info);
|
||||
|
||||
mask-position: center;
|
||||
mask-repeat: no-repeat;
|
||||
mask-size: contain;
|
||||
mask-image: var(--admonition-icon--info);
|
||||
|
||||
-webkit-mask-position: center;
|
||||
-webkit-mask-repeat: no-repeat;
|
||||
-webkit-mask-size: contain;
|
||||
-webkit-mask-image: var(--admonition-icon--info);
|
||||
|
||||
display: inline-block;
|
||||
margin-right: .4em;
|
||||
vertical-align: bottom;
|
||||
|
||||
height: 1.5em;
|
||||
width: 1.5em;
|
||||
}
|
||||
|
||||
.admonition.note {
|
||||
background-color: var(--admonition-background-color--note);
|
||||
border-color: var(--admonition-border-color--note);
|
||||
}
|
||||
|
||||
.admonition-icon.note::before {
|
||||
background-color: var(--admonition-border-color--note);
|
||||
|
||||
mask-image: var(--admonition-icon--note);
|
||||
-webkit-mask-image: var(--admonition-icon--note);
|
||||
}
|
||||
|
||||
.admonition.warning {
|
||||
background-color: var(--admonition-background-color--warning);
|
||||
border-color: var(--admonition-border-color--warning);
|
||||
}
|
||||
|
||||
.admonition-icon.warning::before {
|
||||
background-color: var(--admonition-border-color--warning);
|
||||
|
||||
mask-image: var(--admonition-icon--warning);
|
||||
-webkit-mask-image: var(--admonition-icon--warning);
|
||||
}
|
||||
|
||||
.admonition.tip {
|
||||
background-color: var(--admonition-background-color--tip);
|
||||
border-color: var(--admonition-border-color--tip);
|
||||
}
|
||||
|
||||
.admonition-icon.tip::before {
|
||||
background-color: var(--admonition-border-color--tip);
|
||||
|
||||
mask-image: var(--admonition-icon--tip);
|
||||
-webkit-mask-image: var(--admonition-icon--tip);
|
||||
}
|
||||
|
||||
.admonition.question {
|
||||
background-color: var(--admonition-background-color--question);
|
||||
border-color: var(--admonition-border-color--question);
|
||||
}
|
||||
|
||||
.admonition-icon.question::before {
|
||||
background-color: var(--admonition-border-color--question);
|
||||
|
||||
mask-image: var(--admonition-icon--question);
|
||||
-webkit-mask-image: var(--admonition-icon--question);
|
||||
}
|
||||
|
||||
.admonition-content > *:last-child {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
|
@ -8,7 +8,7 @@ eleventyNavigation:
|
|||
|
||||
Instead of using the `codeberg.page` Domain, you can also purchase your own domain from your internet service provider of your choice and configure it to serve content from Codeberg Page.
|
||||
|
||||
> **Currently known pitfalls for failed certificates:**
|
||||
> **Currently known pitfalls for failed certificates:**<br />
|
||||
> - you must either not have a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization#Record), or explicitly allow [LetsEncrypt](https://letsencrypt.org) there
|
||||
|
||||
For custom domains, two things are required:
|
||||
|
|
@ -23,7 +23,7 @@ For custom domains, two things are required:
|
|||
|
||||
<br />
|
||||
|
||||
> **Why do I need all these DNS records?** <br />
|
||||
> **Why do I need all these DNS records?**<br />
|
||||
> To understand how the Pages Server serves content, you need to know that a user browsing your custom domain just sends "Hey, I want to see `yourdomain.com`" to the server. But the server might not know, that it is responsible for `yourdomain.com` and it cannot just server all domains in the world. So to find out if the server is responsible for `yourdomain.com` it will check the DNS entries of `yourdomain.com`. If it returns something with `codeberg.page` (according to the domain schemes mentioned below) then it knows, which respository to check for the `.domains` file and your content.
|
||||
|
||||
## Setting the DNS record
|
||||
|
|
@ -74,7 +74,7 @@ The easiest and recommended way is to just setup a CNAME record for your domain,
|
|||
|
||||
<br />
|
||||
|
||||
> **⚠️ Caution** <br />
|
||||
> **⚠️ Caution**<br />
|
||||
> With a CNAME record everything on this domain is delegated to codeberg.page, which means you cannot setup your own e-mail adress with this method. If you need e-mail or others services, you have to use one of the remaining options.
|
||||
|
||||
**Option 2: ALIAS record**
|
||||
|
|
@ -228,7 +228,7 @@ For the DNS configuration:
|
|||
|
||||
In this case, we want our *Project* pages available at the URL `https://example.com`.
|
||||
|
||||
> Note: this would be incompatible with using the apex `example.com` for other purposes, e.g. for the *Personal*/*Organization* example discussed before.
|
||||
> Note: This would be incompatible with using the apex `example.com` for other purposes, e.g. for the *Personal*/*Organization* example discussed before.
|
||||
|
||||
The `.domains` file contains the following:
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@ Almost everything on Codeberg happens in a repository. Think of a repository as
|
|||
This article will guide you through creating your first repository on Codeberg, connecting your local development environment and making your first commit.
|
||||
|
||||
## Creating a Repository
|
||||
|
||||
> A note to more advanced users: It's currently not possible to use Push-to-Create to push a fresh repository onto Codeberg.
|
||||
|
||||
To create a new repository, you need be logged in to your account on Codeberg.org.
|
||||
|
|
@ -141,7 +142,7 @@ knut@iceberg:~/my-project$ git remote add origin https://codeberg.org/knut/fooba
|
|||
|
||||
If all is done correctly, this command should output nothing.
|
||||
|
||||
> **Errors:**
|
||||
> **Errors**<br />
|
||||
> If you added an already initalized remote repository and try to push, you will get an error, if your local commit history is different from the history of the remote. You have some choices to resolve the conflict:
|
||||
> - Merge your changes with the ones in the remote `git pull`
|
||||
> - If you are sure, that you want to overwrite all changes in the remote, you can force push with `git -f push`
|
||||
|
|
|
|||
|
|
@ -56,7 +56,6 @@ your security.
|
|||
|
||||
> Please visit the [guide in the security section](/security/2fa) to learn how to set up 2FA.
|
||||
|
||||
|
||||
## Moving on from here
|
||||
Now that you have an account on Codeberg, you can choose from a number of possible ways to explore:
|
||||
|
||||
|
|
|
|||
|
|
@ -106,6 +106,7 @@ git update-git-for-windows
|
|||
After that, just follow the instructions in the terminal to update to the latest version.
|
||||
|
||||
Alternatively, you can download the installer from the Git website as explained above.
|
||||
|
||||
> Make sure that you run the new installer with the same permissions (Administrator or standard user) as the original installation. If not, it will be installed twice and that will create a mess.
|
||||
|
||||
If you want to keep all your previous settings, simply tick the box `Only show new options` in the setup wizard (see screenshots above).
|
||||
|
|
|
|||
|
|
@ -157,17 +157,52 @@ Favor “self-contained information units” over interconnected information uni
|
|||
|
||||
### Notes and warnings
|
||||
|
||||
Keep notes and warnings outside the body of your running text. Use appropriate Markdown syntax to display notes and warnings, e.g. using the following markdown syntax:
|
||||
Keep notes and warnings outside the body of your running text. Use admonition boxes, also known as callouts, to show said information.
|
||||
|
||||
```markdown
|
||||
> **Note:**
|
||||
> Always write the names of measurement units in lowercase letters, i.e. use “watt” instead of “Watt”.
|
||||
The syntax is as follows:
|
||||
```
|
||||
{% raw %}
|
||||
{% admonition "type" "title [optional]" %}
|
||||
|
||||
which will be rendered as:
|
||||
Content
|
||||
|
||||
> **Note:**
|
||||
> Always write the names of measurement units in lowercase letters, i.e. use “watt” instead of “Watt”.
|
||||
{% endadmonition %}
|
||||
{% endraw %}
|
||||
```
|
||||
If no title is provided will the admonition box default to the type being used as title.<br>
|
||||
Note the gaps between the content and the start and end tag. These are required to allow markdown to be rendered.
|
||||
|
||||
The following admonition types are currently available:
|
||||
|
||||
{% admonition "info" %}
|
||||
|
||||
Default type used should no type or an invalid one be provided. Should be used to give short and useful information to know about.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
{% admonition "note" %}
|
||||
|
||||
Can be used to provide short snippets of information.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
{% admonition "warning" %}
|
||||
|
||||
Use to indicate possible issues and problems, or known pitfalls a user should look out for.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
{% admonition "tip" %}
|
||||
|
||||
Can be used to give suggestions and hints to a user.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
{% admonition "question" %}
|
||||
|
||||
Use to show and answer a question the user may ask in this situation.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
### Topic typology
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue