This doc page is specific to Scala 3, and may cover new concepts not available in Scala 2. Unless otherwise stated, all the code examples in this page assume you are using Scala 3.
Scaladoc allows you to include a simple blog in your documentation. For now, it provides only basic features. In the future, we plan to include more advanced features like tagging or author pages.
Blog is treated a little differently than regular static sites. This article will help you set up your own blog.
Proper directory setup
All your blogposts must be put under _blog/_posts directory.
├── _blog
│ ├── _posts
│ │ └── 2016-12-05-implicit-function-types.md
│ └── index.html
Scaladoc loads blog if the _blog directory exists.
Naming convention
All the blogpost filenames should start with date in numeric format matching YYYY-MM-DD.
Example name is 2015-10-23-dotty-compiler-bootstraps.md.
Page metadata
The blog pages in scaladoc support Yaml Frontmatter which allows you to specify different values which will be used for metadata in your page. Here are the possible fields:
---
layout: <A reference to the layout page for the blog page>
author: <Name of the author of the page>
title: <Title of the page>
subTitle: <Subtitle of the page>
date: <Date of the creation of the page>, e.g. 2016-12-05
authorImg: <Link to the author's image>
---
<Content of your page>
You can also find more details about the front matter on the Jekyll documentation site.
Syntax of the content
Keep in mind that the writing of your blog is done with Markdown. You can find more information about the syntax in Markdown Guide.
Blog configuration
When creating your blog, Scaladoc also allows you to configure it.
In order to modify the default settings of the blog documentation, users need to create a file named blog.yml in the root directory of the blog. The file should contain the parameters that the user wants to change. For example, if a user wants to change the input directory to “my_posts”, the output directory to “my_docs”, and temporarily hide the blog, they can create a file with the following content:
input: my_posts
output: my_docs
hidden: true
Parameters:
input: specifies the directory containing markdown files for the blog posts (default: “_posts” in “docs”).
output: specifies the folder where HTML pages will be generated (default: “blog” in “target/docs”).
hidden: allows users to temporarily hide the blog (default: “false”).
To change these settings, create a file with the parameters and save it in the blog’s root directory. The next time the blog is built, the new settings will be used.