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.

Configuration

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.

Colours

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.

Dimensions

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)

Fonts

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.

Miscellaneous

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.

Document sections

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.

Scrolling progress indicator

<nav id="scroller"></nav>

Top navigation bar

<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>

Splash screen

<header>
  <img>
  <span class="title"></span>
  <span class="subtitle"></span>
</header>

Page content

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.

Side navigation bars

<aside id="toc"></aside>

Search

<aside id="search">
  <header>
    <span class="search"></span>
    <input id="search-input">
    <span class="reset"></span>
  </header>
  <ul id="search-output"></ul>
</aside>

Main content

<article>
  <div></div>
  <span class="spacer"></span>
  <footer>
    <a id="prev"></a>
    <span class="spacer"></span>
    <a id="next"></a>
  </footer>
</article>

Article content

Preceding and following articles

Markup

The styling code associated with HTML constructs (native and/or custom) is defined in the style-markup.css file.

CSS imports

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.

`@media` rules

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.

carnarez / markdown-render-styling Goto Github PK

markdown-render-styling's Introduction

Configuration

Colours

Dimensions

Fonts

Miscellaneous

Document sections

Scrolling progress indicator

Top navigation bar

Splash screen

Page content

Side navigation bars

Table of Contents

Search

Main content

Article content

Preceding and following articles

Markup

CSS imports

@media rules

markdown-render-styling's People

Contributors

Watchers

Recommend Projects

Recommend Topics

Recommend Org

`@media` rules