Merge pull request #2323 from pikinier20/static-site-update

Update static site docs

Author: julienrf

_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
 

_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
+.
+└── <site-root>/
+    └── _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 `<static-root>/_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
-
+.
+└── <site-root>/
+    ├── _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`.