Build the microsite
Once you have written your documents, you can build the microsite running this sbt task:
Starting on version
1.0.0 you can build microsites including different versions of your library. This is available for the
light theme, and you need to have
git installed and available in your system. Most probably you already have it, but in other case please check your system docs, or go to the git website on how to proceed.
The feature is based on the concept of
git tags. If you have different tags on your library repository, and they include
sbt-microsites as part of their builds, specify the versions you want to serve in a list with their tag names, through the setting
micrositeVersionList := List("0.1.0", "0.2.0")
Then, run the following task:
page layouts will include a selector pointing to those version specific microsites main sites on their top navbars.
View the microsite in your browser
If you’re running the microsite locally, you can follow these steps:
In a shell, navigate to the generated site directory in
Start Jekyll with
jekyll serve. Bear in mind that depending on your
micrositeBaseUrlsetting, you might need to serve the site setting the base url. Execute Jekyll appending that value
jekyll serve -b /yourbase_url
Navigate to http://localhost:4000/ or http://localhost:4000/yourbase_url/ in your browser, where
yourbase_urldepends on your own preferences (see
micrositeBaseUrlsetting). Note, if you haven’t specified any
micrositeBaseUrlsetting, it’ll be empty by default.
Publish the microsite
0.5.4, you have two options to publish the site:
- sbt-ghpages: This is the default method. It uses the sbt-git plugin and the local ssh keys for pushing the changes.
- github4s: Avoids using local ssh keys, publishing the site through the GitHub HTTP API and Github4s. By contrast, you need to specify a token.
Before publishing, a couple of requirements should be satisfied:
- Initialize the gh-pages branch, you can follow the instructions defined in the sbt-ghpages repository.
micrositeGithubReposettings and maybe the
micrositeGithubReposettings. You can see more details regarding this in the Configuring the Microsite section.
Once both requirements are satisfied, you can just run:
And that’s all. Behind the scenes,
pushSite are invoked.
By default, the second task uses the
If you don’t have any domain names pointing to your site, you can see your microsite at: