Basic styling for my own projects documentation pages. To be used with the
template
included in and rendered by the code from the
markdown-render
repo. The crude
light/dimmed/dark themes and syntax highlighting were [quite shamelessly] forked from
GitHub colour scheme for my own sense of symmetry and consistency.
Structure of this little codebase:
style-markup.css
defines styles for native and custom HTML tags;style-struct.css
defines styles for the generated pages sections;style-syntax.css
defines styles for syntax highlighting for code snippets;style.css
defines configuration variables and imports the content above to be bundled.
See below for a more detailed description of the defined CSS.
The whole "design" of the minimalistic HTML pages requires a few colours, dimensions and fonts:
background-color
: default background colour,background-color-alt
: alternative background colour,font-color
: default text colour,link-color
: default clickable link color,font-family
: default font for all text,font-family-monospace
: monospace font (for code snippets),font-size
: common font size used by most browsers,line-height
: height of a line of text,icon-size
: size of the icons,article-width
: max width of the text container,side-nav-width
: width of the side navigation bar,top-nav-height
: height of the top navigation bar,transition-duration
: duration for CSS transitions.
These variables are defined in the style.css
file.
Variable name | Light | Dark | Dimmed |
---|---|---|---|
background-color |
#ffffff |
#0d1117 |
#22272e |
background-color-alt |
#f3f5f7 |
#161b22 |
#2d333b |
font-color |
#24292e |
#c9d1d9 |
#adbac7 |
link-color |
#0969da |
#539bf5 |
#539bf5 |
The light theme is default.
Variable name | Value |
---|---|
font-size |
16px (equals to 1rem ) |
line-height |
2rem (dependent on the font size) |
icon-size |
1.25rem (dependent on the font size) |
article-width |
1000px |
side-nav-width |
40% |
top-nav-height |
5rem (dependent on the font size) |
Variable name | Value |
---|---|
font-family |
Arial , sans-serif |
font-family-monospace |
Consolas , monospace |
The default font families are chosen from the list of web safe fonts.
Variable name | Value |
---|---|
transition-duration |
0.5s |
Note the duration parameter is currently applied on the following
CSS transitions:
background-color
, border-color
, color
, left
, margin
, opacity
,
text-decoration-color
, width
.
Full HTML code
Below the full [pseudo-]code of the body
tag of the HTML template. The "design" is
kept as minimalistic as possible, leaving to CSS most of the work.
<body>
<nav id="scroller"></nav>
<nav id="topbar">
<div>
<a class="sidebar"></a>
<a class="search"></a>
<span class="spacer"></span>
<a class="logo"><img></a>
<span class="spacer"></span>
<a class="repo"></a>
<a class="theme"></a>
</div>
</nav>
<header>
<img src="splash">
<span class="title"></span>
<span class="description"></span>
</header>
<main>
<aside id="toc">toc</aside>
<aside id="search">
<header>
<span class="search"></span>
<input id="search-input">
<span class="reset"></span>
</header>
<ul id="search-output"></ul>
</aside>
<article>
<div></div>
<span class="spacer"></span>
<footer>
<a id="prev"></a>
<span class="spacer"></span>
<a id="next"></a>
</footer>
</article>
</main>
</body>
The high-level content of the document body
is defined as follows:
<body>
<nav id="scroller"></nav>
<nav id="topbar"></nav>
<header></header>
<main></main>
</body>
See below for a detailed description of the styles applied on the children sections.
The styling code associated with the sections described below is defined in the
style-struct.css
file.
<nav id="scroller"></nav>
<nav id="topbar">
<div>
<a class="toc"></a>
<a class="search"></a>
<span class="spacer"></span>
<a class="logo"><img></a>
<span class="spacer"></span>
<a class="repo"></a>
<a class="theme"></a>
</div>
</nav>
<header>
<img>
<span class="title"></span>
<span class="subtitle"></span>
</header>
The high-level content of the main
section is defined as follows:
<main>
<aside id="toc"></aside>
<aside id="search"></aside>
<article></article>
</main>
See below for a detailed description of the styles applied on the children entities.
<aside id="toc"></aside>
<aside id="search">
<header>
<span class="search"></span>
<input id="search-input">
<span class="reset"></span>
</header>
<ul id="search-output"></ul>
</aside>
<article>
<div></div>
<span class="spacer"></span>
<footer>
<a id="prev"></a>
<span class="spacer"></span>
<a id="next"></a>
</footer>
</article>
The styling code associated with HTML constructs (native and/or custom) is defined in
the style-markup.css
file.
The free Solid, Regular & Brands Font Awesome icon sets are made available.
The CSS necessary to render mathematical equations using the
KaTeX
package is added to the mix, regardless of whether
equations can be found in the document.
Syntax highlighting is applied client-side (via
highlight.js
) and requires a specific set of (18!) colours
to be defined. The latter can be fetched and aggregates from "official" themes (look for
them in the
src/styles/
directory of the highlight.js
repo).
Fetch GitHub colours
Below assumption is, all CSS definitions are in the same order in each of the files scanned.
function extract_hex {
grep -e 'background:' -e 'color:' $1 | sed 's/;$//g' | awk '{print$NF}'
}
function format_vars {
extract_hex $1 | cat -n | sed 's/^[ ]*/ --color-/g;s/\t/: /g;s/$/;/g'
}
src=https://raw.githubusercontent.com/highlightjs/highlight.js/main/src/styles
wget -qq $src/github.css
wget -qq $src/github-dark.css
wget -qq $src/github-dark-dimmed.css
echo '/* stylelint-disable selector-class-pattern */'
echo
echo '/*
* source themes downloaded from:
* https://github.com/highlightjs/highlight.js/tree/main/src/styles
* and merged to account for the theme switch
*/'
echo
echo -e ":root,\n.light {"
format_vars github.css
echo '}'
echo
echo '.dark {'
format_vars github-dark.css
echo '}'
echo
echo '.dimmed {'
format_vars github-dark-dimmed.css
echo '}'
echo
awk '/.hljs/,0' github-dark-dimmed.css > .tmp-theme
format_vars github-dark-dimmed.css | while read line; do
var=$(awk '{print$1}' <<< $line | sed 's/://g')
hex=$(awk '{print$2}' <<< $line | sed 's/;//g')
sed -i "s/$hex/var\($var\)/" .tmp-theme
done
cat .tmp-theme
rm .tmp-theme github*.css
External imports are defined in the style.css
file, while colours and
style mappings associated with syntax highlighting are defined in the
style-syntax.css
file.
The only @media
rules applied on the defined styles are regarding the side navigation
bars (by default taking the whole screen, but taking a percentage of the latter on
larger displays) and the preceding/following articles links (on top of each other and
taking the whole width of the screen by default, but side-by-side and with a fixed
dimension for larger display).
@media
rules are defined in the style-struct.css
file.