Update static site docs #2323

pikinier20 · 2022-02-08T14:26:56Z

No description provided.

julienrf · 2022-02-08T14:35:12Z

_overviews/scala3-scaladoc/static-site.md

-│   └── getting-started.md
-└── index.html
+└── _docs
+    └── getting-started.md


Should we add back the index.html file, for consistency with the previous examples?

julienrf · 2022-02-08T14:35:41Z

_overviews/scala3-scaladoc/static-site.md

+└── _docs
+    └── getting-started.md
+```
+To reference the asset in a page, one need to create link relative to the `_assets` directory


Suggested change

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

julienrf · 2022-02-08T14:36:14Z

_overviews/scala3-scaladoc/static-site.md

 ```

 ## 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 layout of files in `_docs` directory to render static site. There is also ability 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:


Suggested change

Scaladoc by default uses layout of files in `_docs` directory to render static site. There is also ability 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 uses the layout of the files in the `_docs` directory to render the static 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:

julienrf · 2022-02-08T14:51:24Z

_overviews/scala3-scaladoc/static-site.md

+          hidden: false
+```
+The `rootIndex` property defines the root page of a static site: `_docs/index.html`
+The `pages` key is mandatory. Its value should be array of `subsection` or `page`.


Suggested change

The `pages` key is mandatory. Its value should be array of `subsection` or `page`.

The `pages` key is mandatory. Its value should be an array of `subsection` or `page`.

julienrf · 2022-02-08T14:52:09Z

_overviews/scala3-scaladoc/static-site.md

+ - `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.


Suggested change

- `directory` - Optional string - A name of the directory that will contain the subsection.

- `directory` - Optional string - A name of the directory that will contain the subsection in the generated site.

julienrf · 2022-02-08T14:56:25Z

_overviews/scala3-scaladoc/static-site.md

+ - `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 `<static-root>/_docs`.


Suggested change

**Note**: All paths in YAML configuration file are relative to `<static-root>/_docs`.

**Note**: All the paths in the YAML configuration file are relative to `<static-root>/_docs`.

julienrf · 2022-02-08T14:58:45Z

_overviews/scala3-scaladoc/static-site.md

 ```
+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.


Suggested change

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.

julienrf · 2022-02-08T14:59:39Z

_overviews/scala3-scaladoc/static-site.md


-```
-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.


Suggested change

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 output directory structure.

julienrf · 2022-02-08T15:00:15Z

_overviews/scala3-scaladoc/static-site.md

-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:


Suggested change

Take a look at following subsection definition:

Take a look at the following subsection definition:

julienrf · 2022-02-08T15:03:13Z

_overviews/scala3-scaladoc/static-site.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`.


Suggested change

Even though the index page and all defined children are in different directories, they will be rendered in `custom-directory`.

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`.

julienrf · 2022-02-15T12:22:13Z

Is this ready for review?

pikinier20 · 2022-03-09T09:41:56Z

Is this ready for review?

Now it's ready :)

julienrf · 2022-03-09T12:58:12Z

I see several comments/suggestions not taken into account. Could you please address them?

pikinier20 mentioned this pull request Feb 8, 2022

Scaladoc: Refactor static site loading and directory structure scala/scala3#14378

Merged

julienrf marked this pull request as draft February 8, 2022 14:31

julienrf reviewed Feb 8, 2022

View reviewed changes

Update static site docs

9097144

pikinier20 force-pushed the static-site-update branch from 57dbc50 to 9097144 Compare March 9, 2022 09:41

Apply suggestions from review

6e2cf92

pikinier20 marked this pull request as ready for review March 10, 2022 08:05

bishabosha requested a review from julienrf March 10, 2022 09:08

bishabosha assigned julienrf Mar 10, 2022

julienrf merged commit 705ae51 into scala:main Mar 11, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update static site docs #2323

Update static site docs #2323

pikinier20 commented Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf Feb 8, 2022

julienrf commented Feb 15, 2022

pikinier20 commented Mar 9, 2022

julienrf commented Mar 9, 2022

	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

	Scaladoc by default uses layout of files in `_docs` directory to render static site. There is also ability 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 uses the layout of the files in the `_docs` directory to render the static 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:

	The `pages` key is mandatory. Its value should be array of `subsection` or `page`.
	The `pages` key is mandatory. Its value should be an array of `subsection` or `page`.

	- `directory` - Optional string - A name of the directory that will contain the subsection.
	- `directory` - Optional string - A name of the directory that will contain the subsection in the generated site.

	Note: All paths in YAML configuration file are relative to `<static-root>/_docs`.
	Note: All the paths in the YAML configuration file are relative to `<static-root>/_docs`.

		```
		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 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.

	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 output directory structure.

	Take a look at following subsection definition:
	Take a look at the following subsection definition:

	Even though the index page and all defined children are in different directories, they will be rendered in `custom-directory`.
	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`.

Update static site docs #2323

Update static site docs #2323

Conversation

pikinier20 commented Feb 8, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

julienrf commented Feb 15, 2022

pikinier20 commented Mar 9, 2022

julienrf commented Mar 9, 2022