diff --git a/_overviews/scala3-scaladoc/blog.md b/_overviews/scala3-scaladoc/blog.md index 1e3c371c8..612ee5c25 100644 --- a/_overviews/scala3-scaladoc/blog.md +++ b/_overviews/scala3-scaladoc/blog.md @@ -15,24 +15,17 @@ Blog is treated a little differently than regular static sites. This article wil ## Proper directory setup -All your blogposts must be put under `blog/_posts` directory. +All your blogposts must be put under `_blog/_posts` directory. ``` -├── blog +├── _blog │ ├── _posts │ │ └── 2016-12-05-implicit-function-types.md │ └── index.html ``` -If you are using yaml [sidebar]({% link _overviews/scala3-scaladoc/static-site.md %}#sidebar) don't forget to place - -``` -sidebar: - - title: Blog -``` - -somewhere inside the `yaml` tree representing the sidebar sections. Scaladoc will attach under that section all of your blogposts. +Scaladoc loads blog if the `_blog` directory exists. ## Naming convention diff --git a/_overviews/scala3-scaladoc/static-site.md b/_overviews/scala3-scaladoc/static-site.md index e7516ea09..127f6c59e 100644 --- a/_overviews/scala3-scaladoc/static-site.md +++ b/_overviews/scala3-scaladoc/static-site.md @@ -20,16 +20,18 @@ and will from here on be referred to as "template files" or "templates". A simple "hello world" site could look something like this: ``` -├── docs -│ └── getting-started.md -└── index.html +. +└── / + └── _docs/ + ├── index.html + └── getting-started.html ``` This will give you a site with the following files in generated documentation: ``` index.html -docs/getting-started.html +getting-started.html ``` Scaladoc can transform both files and directories (to organize your documentation into a tree-like structure). By default, directories have a title based on the file name and have empty content. It is possible to provide index pages for each section by creating `index.html` or `index.md` (not both) in the dedicated directory. @@ -98,63 +100,65 @@ Layouts must be placed in a `_layouts` directory in the site root: ``` ├── _layouts │ └── main.html -├── docs -│ └── getting-started.md -└── index.html +└── _docs + ├── getting-started.md + └── index.html +``` + +## Assets + +In order to render assets along with static site, they need to be placed in the `_assets` directory in the site root: +``` +├── _assets +│ └── images +│ └── myimage.png +└── _docs + └── getting-started.md +``` +To reference the asset on a page, one needs to create a link relative to the `_assets` directory + +``` +Take a look at the following image: [My image](images/myimage.png) ``` ## Sidebar -Scaladoc by default uses layout of files in `docs` directory to create table of content. There is also ability to override it by providing a `sidebar.yml` file in the site root: +By default, Scaladoc reflects the directory structure from `_docs` directory in the rendered site. There is also the ability to override it by providing a `sidebar.yml` file in the site root directory. The YAML configuration file describes the structure of the rendered static site and the table of content: ```yaml -sidebar: - - title: Blog - - title: My title - page: my-page1.md - - page: my-page2.md - - page: my-page3/subsection - - title: Reference - subsection: - - page: my-page3.md - - index: my-page4/index.md - subsection: - - page: my-page4/my-page4.md - - title: My subsection - index: my-page5/index.md - subsection: - - page: my-page5/my-page5.md - - index: my-page6/index.md - subsection: - - index: my-page6/my-page6/index.md - subsection: - - page: my-page6/my-page6/my-page6.md -``` - -The `sidebar` key is mandatory. -On each level, you can have three different types of entries: `page`, `blog` or `subsection`. - -`page` is a leaf of the structure and accepts the following attributes: -- `title` (optional) - title of the page -- `page` (mandatory) - path to the file that will represent the page, it can be either html or markdown file to be rendered, there is also the possibility to pass the `directory` path. If so, the scaladoc will render the directory and all its content as if there were no `sidebar.yml` basing on its tree structure and index files. - -The `page` property `subsection` accepts nested nodes, these can be either pages or subsections, which allow you to create tree-like navigation. The attributes are: -- `title` (optional) - title of the page -- `index` (optional) - path to the file that will represent the index file of the subsection, it can be either html or markdown file to be rendered -- `subsection` (mandatory) - nested nodes, can be either pages or subsections - -In `subsection`s, you can omit `title` or `index`, however not specifying any of these properties prevents you from specifying the title of the section. - -`blog` is a special node represented by simple entry `- title: Blog` with no other attributes. All your blog posts will be automatically linked under this section. You can read more about the blog [here]({% link _overviews/scala3-scaladoc/blog.md %}). - -``` -├── blog -│ ├── _posts -│ │ └── 2016-12-05-implicit-function-types.md -│ └── index.html -├── index.html -└── sidebar.yml -``` +index: index.html +subsection: + - title: Usage + index: usage/index.html + directory: usage + subsection: + - title: Dottydoc + page: usage/dottydoc.html + hidden: false + - title: sbt-projects + page: usage/sbt-projects.html + hidden: false +``` +The root element needs to be a `subsection`. +Nesting subsections will result in a tree-like structure of navigation. + +`subsection` properties are: + - `title` - Optional string - A default title of the subsection. + Front-matter titles have higher priorities. + - `index` - Optional string - A path to index page of a subsection. The path is relative to the `_docs` directory. + - `directory` - Optional string - A name of the directory that will contain the subsection in the generated site. + By default, the directory name is the subsection name converted to kebab case. + - `subsection` - Array of `subsection` or `page`. + + Either `index` or `subsection` must be defined. The subsection defined with `index` and without `subsection` will contain pages and directories loaded recursively from the directory of the index page. + +`page` properties are: + - `title` - Optional string - A default title of the page. + Front-matter titles have higher priorities. + - `page` - String - A path to the page, relative to the `_docs` directory. + - `hidden` - Optional boolean - A flag that indicates whether the page should be visible in the navigation sidebar. By default, it is set to `false`. + +**Note**: All the paths in the YAML configuration file are relative to `/_docs`. ## Hierarchy of title @@ -174,30 +178,45 @@ If the title is specified multiple times, the priority is as follows (from highe Note that if you skip the `index` file in your tree structure or you don't specify the `title` in the frontmatter, there will be given a generic name `index`. The same applies when using `sidebar.yml` but not specifying `title` nor `index`, just a subsection. Again, a generic `index` name will appear. +## Blog +Blog feature is described in [a separate document]({% link _overviews/scala3-scaladoc/blog.md %}) -## Static resources - -You can attach static resources (pdf, images) to your documentation by using two dedicated directories: -`resources` and `images`. After placing your assets under any of these directories, you can reference them in markdown -as if they were relatively at the same level. - -For example, consider the following situation: - +## Advanced configuration +### Full structure of site root ``` -├── blog -│ ├── _posts -│ │ └── 2016-12-05-implicit-function-types.md -│ └── index.html -├── index.html -├── resources -│ └── my_file.pdf -├── images -│ └── my_image.png -└── sidebar.yml - +. +└── / + ├── _layouts_/ + │ └── ... + ├── _docs/ + │ └── ... + ├── _blog/ + │ ├── index.md + │ └── _posts/ + │ └── ... + └── _assets/ + ├── js/ + │ └── ... + ├── img/ + │ └── ... + └── ... ``` +It results in a static site containing documents as well as a blog. It also contains custom layouts and assets. The structure of the rendered documentation can be based on the file system but it can also be overridden by YAML configuration. -You can refer to the assets from within any of the files using markdown links: +### Mapping directory structure -``` -This is my blog post. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)``` +Using the YAML configuration file, we can define how the source directory structure should be transformed into an outputs directory structure. + +Take a look at the following subsection definition: +```yaml +- title: Some other subsection + index: abc/index.html + directory: custom-directory + subsection: + - page: abc2/page1.md + - page: foo/page2.md +``` +This subsection shows the ability of YAML configuration to map the directory structure. +Even though the index page and all defined children are in different directories, they will be rendered in `custom-directory`. +The source page `abc/index.html` will generate a page `custom-directory/index.html`, the source page `abc2/page1.md` will generate a page `custom-directory/page1.html`, +and the source page `foo/page2.md` will generate a page `custom-directory/page2.html`.