From 9097144e071d4290dc165aee2e2855c48aae64dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Zyba=C5=82a?= Date: Tue, 8 Feb 2022 15:13:34 +0100 Subject: [PATCH 1/2] Update static site docs --- _overviews/scala3-scaladoc/blog.md | 13 +- _overviews/scala3-scaladoc/static-site.md | 170 ++++++++++++---------- 2 files changed, 96 insertions(+), 87 deletions(-) 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..d9d11f6bf 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,64 @@ 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 +``` + +## 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 in a page, one need to create 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: +Scaladoc by default uses directory structure in `_docs` directory to organize static sites. There is also possibility to override it by providing a `sidebar.yml` file in the site root. The YAML configuration file describes the structure of 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. + - `directory` - Optional string - A name of the directory that will contain the subsection. + 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 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 + - `hidden` - Optional boolean - A flag that indicates whether the page should be visible in navigation. By default, it is set to `false`. + +**Note**: All paths in YAML configuration file are relative to `/_docs`. ## Hierarchy of title @@ -174,30 +177,43 @@ 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 static site containing documents as well as blog. It also contains custom layouts and assets. The structure of rendered documentation can be based on file system but it can also be overriden 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 YAML configuration file, we can define how the source directory structure should be transformed in target directory structure. + +Take a look at 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`. From 6e2cf92d84dc4ee4290dc65cd83f2a4a4b250796 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Zyba=C5=82a?= Date: Thu, 10 Mar 2022 09:05:31 +0100 Subject: [PATCH 2/2] Apply suggestions from review --- _overviews/scala3-scaladoc/static-site.md | 27 +++++++++++++---------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/_overviews/scala3-scaladoc/static-site.md b/_overviews/scala3-scaladoc/static-site.md index d9d11f6bf..127f6c59e 100644 --- a/_overviews/scala3-scaladoc/static-site.md +++ b/_overviews/scala3-scaladoc/static-site.md @@ -101,7 +101,8 @@ Layouts must be placed in a `_layouts` directory in the site root: ├── _layouts │ └── main.html └── _docs - └── getting-started.md + ├── getting-started.md + └── index.html ``` ## Assets @@ -114,7 +115,7 @@ In order to render assets along with static site, they need to be placed in the └── _docs └── getting-started.md ``` -To reference the asset in a page, one need to create link relative to the `_assets` directory +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) @@ -122,7 +123,7 @@ Take a look at the following image: [My image](images/myimage.png) ## Sidebar -Scaladoc by default uses directory structure in `_docs` directory to organize static sites. There is also possibility to override it by providing a `sidebar.yml` file in the site root. The YAML configuration file describes the structure of rendered static site and the table of content: +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 index: index.html @@ -144,20 +145,20 @@ 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. - - `directory` - Optional string - A name of the directory that will contain the subsection. + - `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 directory of the index 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 - - `hidden` - Optional boolean - A flag that indicates whether the page should be visible in navigation. By default, it is set to `false`. + - `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 paths in YAML configuration file are relative to `/_docs`. +**Note**: All the paths in the YAML configuration file are relative to `/_docs`. ## Hierarchy of title @@ -200,13 +201,13 @@ Blog feature is described in [a separate document]({% link _overviews/scala3-sca │ └── ... └── ... ``` -It results in static site containing documents as well as blog. It also contains custom layouts and assets. The structure of rendered documentation can be based on file system but it can also be overriden by YAML configuration. +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. ### Mapping directory structure -Using YAML configuration file, we can define how the source directory structure should be transformed in target directory structure. +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 following subsection definition: +Take a look at the following subsection definition: ```yaml - title: Some other subsection index: abc/index.html @@ -217,3 +218,5 @@ Take a look at following subsection definition: ``` 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`.