-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'develop' into child-pages-docs
- Loading branch information
Showing
69 changed files
with
705 additions
and
1,150 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| Sometimes you may have so many pages that the navigation sidebar feels cluttered, even when using child pages. Page sections can be used to simplify the navigation structure. | ||
|
|
||
| Page sections do not have a source file associated with them, but instead have their own nested groups. When the user clicks a page section link in the navigation sidebar, the groups that are nested under that section will be displayed in the sidebar and the previous groups will disappear. Additionally, a new link will be added to the top of the navigation sidebar allowing users to navigate back to the parent groups. | ||
|
|
||
| ## Creating Page Sections | ||
|
|
||
| Follow these steps to create a page section: | ||
|
|
||
| 1. Create a JSON definition for the section: | ||
|
|
||
| ```json | ||
| { | ||
| "title": "My Group", | ||
| "groups": [] | ||
| } | ||
| ``` | ||
|
|
||
| 2. Add the section definition JSON to either: | ||
|
|
||
| - The `pages` array of a page group | ||
| - The `children` array of a parent page | ||
|
|
||
| ## Section Options | ||
|
|
||
| In addition to the required `title` and `groups` properties, page section definitions support two optional properties: | ||
|
|
||
| ### 1. Output | ||
|
|
||
| The optional `output` property supports configuring the name of the directory that pages and groups within the section are rendered to. | ||
|
|
||
| > 👉 For example, the following page definiton would be rendered to `outer-group/my-section/inner-group/my-page.html`: | ||
| ```json | ||
| { | ||
| "groups": [ | ||
| { | ||
| "title": "Outer Group", | ||
| "output": "outer-group", | ||
| "pages": [ | ||
| { | ||
| "title": "My Section", | ||
| "output": "my-section", | ||
| "groups": [ | ||
| { | ||
| "title": "Inner Group", | ||
| "output": "inner-group", | ||
| "pages": [ | ||
| { | ||
| "title": "My Page", | ||
| "source": "my-page.md", | ||
| "output": "my-page.html" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| If no `output` property is provided, the section's title will be used as the default value. | ||
|
|
||
| ### 2. Source | ||
|
|
||
| The optional `source` property allows you to configure a default path prefix for the `source` property of each group within the section. | ||
|
|
||
| > 👉 For example, the following page would be read from `outer-group/my-section/inner-group/my-page.md`: | ||
| ```json | ||
| { | ||
| "groups": [ | ||
| { | ||
| "title": "Outer Group", | ||
| "source": "outer-group", | ||
| "pages": [ | ||
| { | ||
| "title": "My Section", | ||
| "source": "my-section", | ||
| "groups": [ | ||
| { | ||
| "title": "Inner Group", | ||
| "source": "inner-group", | ||
| "pages": [ | ||
| { | ||
| "title": "My Page", | ||
| "source": "my-page.md", | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| By default, no source path prefix is applied when the `source` property is omitted. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| It is possible to use the TypeDoc Pages Plugin with both third-party TypeDoc themes and your own custom themes. Both requires making some small modifications to the themes. | ||
|
|
||
| If you're using your own custom theme, it should be trivial to modify the theme source code. If you're using this plugin with a third-party TypeDoc theme, it is likely that you're consuming the theme via npm. In this scenario, it is recommended that you create a local copy of the theme and make the necessary modifications. | ||
|
|
||
| ## How to modify a TypeDoc theme to support the Pages Plugin: | ||
|
|
||
| The following steps detail the modifications that need to be done to a theme to make it compatible with this plugin: | ||
|
|
||
| 1. Add a Handlebars template for rendering your Markdown pages | ||
|
|
||
| Inside your theme's `templates` directory create a new Handlebars file, `markdown-page.hbs` with the following contents: | ||
|
|
||
| ```handlebars | ||
| <div class="tsd-panel tsd-typography"> | ||
| {{#markdown}}{{{model.pagesPlugin.item.contents}}}{{/markdown}} | ||
| </div> | ||
| ``` | ||
|
|
||
| This is the file that will be responsible for rendering your Markdown pages. You may modify this file to meet the needs of your theme. | ||
|
|
||
| 2. Add custom styles for plugin components | ||
|
|
||
| By default, this plugin will add new items to your theme's existing navigation component. It is a good idea to style these items to best suit your theme. The following is a list of classes, for which you may want to add styling rules to your theme's CSS: | ||
|
|
||
| - `pp-nav`: Class added to all navigation items, including groups, pages, child pages, and sections | ||
| - `pp-group`: Class added to all group navigation items | ||
| - `pp-page`: Class added to all page navigation items | ||
| - `pp-parent`: Class added to all page navigation items that have child pages | ||
| - `pp-active`: Class added to parent page navigation items when the parent page or any of its child pages are the current page | ||
| - `pp-child`: Class added to all child page navigation items | ||
|
|
||
| Additionally, search results for pages added by this plugin will be given the `tsd-kind-page` class. You can customize the icon of these search results with the following styles: | ||
|
|
||
| ```css | ||
| .tsd-kind-page .tsd-kind-icon:before { | ||
| display: inline-block; | ||
| vertical-align: middle; | ||
| height: 16px; | ||
| width: 16px; | ||
| content: ""; | ||
| background-image: url("../images/page-icon.svg"); | ||
| background-size: 16px 16px; | ||
| } | ||
| ``` | ||
|
|
||
| The above code sample will use the image located at `/assets/images/page-icon.svg` for the search result icon. You can find a sample icon image in the built-in theme, [here](https://github.com/mipatterson/typedoc-plugin-pages/blob/master/theme/v2/assets/images/page-icon.svg). | ||
|
|
||
| > NOTE: For styling examples, see the built-in theme's [stylesheet](https://github.com/mipatterson/typedoc-plugin-pages/blob/master/theme/v2/assets/css/pages.css). |
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.