Skip to content

getting-started.md

Latest commit

 

History

History
317 lines (227 loc) · 11.3 KB

getting-started.md

File metadata and controls

317 lines (227 loc) · 11.3 KB
Raw

Getting started

In order to enable the theme add the following line to your project's project/plugins.sbt:

JDK 1.8

@@@ vars

addSbtPlugin("com.github.sbt" % "sbt-paradox-material-theme" % "$project.version$")

@@@

JDK 11+

@@@ vars

addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.10.6")
addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-theme" % "0.10.6")
addSbtPlugin("com.github.sbt" % "sbt-paradox-material-theme" % "$project.version$")

@@@

And enable the theme plugin in your project's build.sbt:

@@ snip build.sbt { #enable-plugin }

Configuring the theme

The theme is configurable via Paradox properties which means that you can provide defaults in your project's build.sbt and override properties in each page's front matter. The preferred way to configure the theme is to use the utility the theme plugin provides which help configure the theme in a concise manner using a builder-like API:

@@ snip build.sbt { #builder-api }

The examples given in the following sections use an alternative syntax. The equivalent of the above configuration using this alternative syntax is:

@@ snip build.sbt { #builder-api-v2 }

In both cases, the theme's configuration is added to the Paradox properties. As a result it is also possible to set properties directly using paradoxProperties or @ref:front matter. Front matter allows you to tweak the look-and-feel for specific pages. The equivalent of the above configuration can be defined in front matter as:

---
material.color.primary: red
material.color.accent: orange
material.logo.icon: cloud
material.copyright: Copyleft © Jonas Fonseca
---

See the following sections for available options.

Changing the color palette

A default hue is defined for every primary and accent color on Google's Material Design color palette, which makes it very easy to change the overall look of the theme. Just set the primary and accent colors using the following variables:

@@ snip build.sbt { #color }

Color names are case-insensitive, but must match the names of the Material Design color palette. Valid values are: red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, grey, blue-grey and white. The last four colors can only be used as a primary color.

If the color is set via this configuration, an additional CSS file that defines the color palette is automatically included. If you want to keep things lean, clone the repository and recompile the theme with your custom colors set. See the guide on @ref:customization for more information.

Primary colors

Click on a tile to change the primary color of the theme:

Red Pink Purple Deep Purple Indigo Blue Light Blue Cyan Teal Green Light Green Lime Yellow Amber Orange Deep Orange Brown Grey Blue Grey White

<script> var buttons = document.querySelectorAll("button[data-md-color-primary]"); Array.prototype.forEach.call(buttons, function(button) { button.addEventListener("click", function() { document.body.dataset.mdColorPrimary = this.dataset.mdColorPrimary; }) }) </script>

Accent colors

Click on a tile to change the accent color of the theme:

Red Pink Purple Deep Purple Indigo Blue Light Blue Cyan Teal Green Light Green Lime Yellow Amber Orange Deep Orange

<script> var buttons = document.querySelectorAll("button[data-md-color-accent]"); Array.prototype.forEach.call(buttons, function(button) { button.addEventListener("click", function() { document.body.dataset.mdColorAccent = this.dataset.mdColorAccent; }) }) </script>

Changing the font family

By default the Roboto font family is included with the theme, specifically the regular sans-serif type for text and the monospaced type for code. Both fonts are loaded from Google Fonts and can be changed to other fonts, like for example the Ubuntu font family:

@@ snip build.sbt { #font }

The text font will be loaded in weights 400 and 700, the monospaced font in regular weight. If you want to load fonts from other destinations or don't want to use the Google Fonts loading magic, just set font to false:

@@ snip build.sbt { #font-disable }

Adding a source repository

To include a link to the repository of your project within your documentation, set the following variables via your project's build.sbt:

@@ snip build.sbt { #repository }

The name of the repository will be rendered next to the search bar on big screens and as part of the main navigation drawer on smaller screen sizes. Furthermore, if the repository is hosted on GitHub, Bitbucker or Gitlab a logo of the service is shown next to the name of the repository. When the type is set to GitHub, the number of stars and forks is shown.

@@@ note { title="Why is there an edit button at the bottom of every article?" .question }

If github.base_url is set, an edit button will appear at the bottom of every article. This behaviour is provided by Paradox. See the Paradox documentation on more guidance regarding the $page.source_url$ attribute, which defines whether the edit button is shown or not.

@@@

Adding a favicon

A favicon can be changed by providing a path toto an .ico or image file:

@@ snip build.sbt { #favicon }

Adding a logo

Your logo should have a rectangular shape with a minimum resolution of 128x128, leave some room towards the edges and be composed of high contrast areas on a transparent ground, as it will be placed on the colored header bar and drawer. Simply create the folder assets/images, add your logo and embed it with:

@@ snip build.sbt { #logo }

If you do not want to include the logo in your site you can also link to the logo using a URI:

@@ snip build.sbt { #logo-uri }

Additionally, the default icon can be changed by setting an arbitrary ligature (or Unicode code point) from the Material Design icon font, e.g.

@@ snip build.sbt { #logo-icon }

Adding social links

Social accounts can be linked in the footer of the documentation using an icon from the FontAwesome webfont. The icons are automatically detected based on the URL:

@@ snip build.sbt { #social }

Open graph metadata

To enable a nice preview of the site in social media, define the following properties in the build:

@@ snip build.sbt { #open-graph }

Copyright Notice

To display a copyright notice in the footer configure the text you want to show. Any HTML markup, such as links, can be used:

@@ snip build.sbt { #copyright }

Language

You can define the language of your site:

@@ snip build.sbt { #language }

This will add a lang attribute to the top-level html element:

<!DOCTYPE html>
<html lang="en" class="no-js">
  ...
</html>

If no language is set English (en) is assumed.

Site search

Site search is enabled by default and will automatically generate a search_index.json file that contains all your site's content and add it to your site. If you want to disable search use:

@@ snip build.sbt { #disable-search }

Search tokenization

The separator for tokenization can also be customized, which makes it possible to index parts of words that are separated by - or . for example:

@@ snip build.sbt { #search-tokenizer }

Google Analytics integration

The theme makes it easy to integrate site tracking with Google Analytics. Besides basic tracking, clicks on all outgoing links can be tracked as well as how site search is used. Tracking can be activated in your project's build.sbt:

@@ snip build.sbt { #analytics }

More advanced customization

If you want to change the general appearance of the Material theme, see @ref:the customization guide for more information.