Skip to content

Styling

Adding this styling to your site is recommended, otherwise things may not look right. You can, of course, adapt and add more.

docs/css/mkdocstrings.css

/* https://mkdocstrings.github.io/crystal/styling.html#recommended-styles */

/* Indent and distinguish sub-items */
div.doc-contents:not(.first) {
  padding-left: 15px;
  border-left: 4px solid rgba(230, 230, 230);
}

mkdocs.yml

extra_css:
  - css/mkdocstrings.css

This is in addition to the mandatory style that mkdocstrings-crystal already inserts (just for reference):

/* Prevent all-caps names in headings */
h5.doc-heading {
  text-transform: none !important;
}

.doc-title {
  font-weight: bold;
}

/* [View source] links don't have brackets by default */
a.doc-source-link::before {
  content: "[";
  color: var(--md-typeset-color);
}
a.doc-source-link::after {
  content: "]";
  color: var(--md-typeset-color);
}

/* Adaptation of https://crystal-lang.org/reference/syntax_and_semantics/documenting_code.html#admonitions to mkdocs-material */

:root {
    /* Icons from https://github.com/Templarian/MaterialDesign/tree/e42f3f41dd46bc033f11c0e5eed7fb742af6e74e/svg */
    /* format-list-checkbox */
    --md-admonition-icon--todo: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21,19V17H8V19H21M21,13V11H8V13H21M8,7H21V5H8V7M4,5V7H6V5H4M3,5A1,1 0 0,1 4,4H6A1,1 0 0,1 7,5V7A1,1 0 0,1 6,8H4A1,1 0 0,1 3,7V5M4,11V13H6V11H4M3,11A1,1 0 0,1 4,10H6A1,1 0 0,1 7,11V13A1,1 0 0,1 6,14H4A1,1 0 0,1 3,13V11M4,17V19H6V17H4M3,17A1,1 0 0,1 4,16H6A1,1 0 0,1 7,17V19A1,1 0 0,1 6,20H4A1,1 0 0,1 3,19V17Z" /></svg>');
    /* close-octagon */
    --md-admonition-icon--deprecated: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8.27,3L3,8.27V15.73L8.27,21H15.73L21,15.73V8.27L15.73,3M8.41,7L12,10.59L15.59,7L17,8.41L13.41,12L17,15.59L15.59,17L12,13.41L8.41,17L7,15.59L10.59,12L7,8.41" /></svg>');
}

/* Based on https://github.com/squidfunk/mkdocs-material/blob/b3c0163b3b6b6e4d2cb4d50fbd535018042c4970/src/assets/stylesheets/main/extensions/markdown/_admonition.scss */

/* "TODO": custom icon */
.md-typeset .todo>.admonition-title:before, .md-typeset .todo>summary:before {
    -webkit-mask-image: var(--md-admonition-icon--todo);
    mask-image: var(--md-admonition-icon--todo);
}

/* "FIXME": "bug" icon, "failure" color */
.md-typeset .admonition.fixme, .md-typeset details.fixme {
    border-color: #ff5252
}
.md-typeset .fixme>.admonition-title, .md-typeset .fixme>summary {
    background-color: rgba(255, 82, 82, .1);
    border-color: #ff5252
}
.md-typeset .fixme>.admonition-title:before, .md-typeset .fixme>summary:before {
    background-color: #ff5252;
    -webkit-mask-image: var(--md-admonition-icon--bug);
    mask-image: var(--md-admonition-icon--bug);
    mask-repeat: no-repeat;
    mask-size: contain
}

/* "DEPRECATED": custom icon, "warning" color */
.md-typeset .admonition.deprecated, .md-typeset details.deprecated {
    border-color: #ff9100
}
.md-typeset .deprecated>.admonition-title, .md-typeset .deprecated>summary {
    background-color: rgba(255, 145, 0, .1);
    border-color: #ff9100
}
.md-typeset .deprecated>.admonition-title:before, .md-typeset .deprecated>summary:before {
    background-color: #ff9100;
    -webkit-mask-image: var(--md-admonition-icon--deprecated);
    mask-image: var(--md-admonition-icon--deprecated);
    mask-repeat: no-repeat;
    mask-size: contain
}

/* "OPTIMIZE": "danger" icon, "question" color */
.md-typeset .admonition.optimize, .md-typeset details.optimize {
    border-color: #64dd17
}
.md-typeset .optimize>.admonition-title, .md-typeset .optimize>summary {
    background-color: rgba(100, 221, 23, .1);
    border-color: #64dd17
}
.md-typeset .optimize>.admonition-title:before, .md-typeset .optimize>summary:before {
    background-color: #64dd17;
    -webkit-mask-image: var(--md-admonition-icon--danger);
    mask-image: var(--md-admonition-icon--danger);
    mask-repeat: no-repeat;
    mask-size: contain
}

Custom styles#

The doc items have consistently applied CSS classes. As of now, there is no separate documentation of what exactly they are. You are recommended to just inspect in the browser whenever you don't like the look of something and see how to reach it in CSS according to the markup.

The above example is some inspiration. Also check out Showcase for more.