-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added support for modern docfx template (#13)
* Started work of supporting new modern template * Updated styles for modern material design. Pending: update documentation and release notes. * Completed support for docfx's modern template
- Loading branch information
Showing
14 changed files
with
403 additions
and
79 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,39 +1,91 @@ | ||
| # DocFX Material | ||
|
|
||
| A simple material theme for [DocFX](https://dotnet.github.io/docfx/). This is an | ||
| override of the default template so you need to enable both in the `docfx.json`. | ||
| override of the **modern** template so you need to enable both in the `docfx.json`. | ||
| The design was inspired by https://m3.material.io/. | ||
|
|
||
| The colors were chosen using <https://material.io/tools/color>. | ||
| If you are looking for the previous version of docfx-material that doesn't use the | ||
| modern template you can still get it as [material-classic](./docs/classic.md). | ||
|
|
||
|  | ||
|  | ||
|
|
||
| ## Install | ||
|
|
||
| 1. Download the source or the zipped file from the [releases](https://github.com/ovasquez/docfx-material/releases). | ||
| 2. Create a `templates` folder in the root of your DocFX directory. | ||
| 3. Copy the `material` folder to the `templates` folder. | ||
| 4. Update the `docfx.json` configuration to include the material template: | ||
| ```json | ||
| { | ||
| "template": [ | ||
| "default", | ||
| "templates/material" | ||
| ], | ||
| } | ||
| ``` | ||
| ```json | ||
| { | ||
| "template": [ | ||
| "default", | ||
| "modern", | ||
| "templates/material" | ||
| ], | ||
| } | ||
| ``` | ||
|
|
||
| ## Color customization | ||
|
|
||
| You can easily customize the color of the header bar and the links by updating | ||
| the following variables in the `material/styles/main.css` file. | ||
| DocFX's modern template is based on Bootstrap 5 (version 5.3 at the time of writing) | ||
| so you can use [Bootstrap's CSS variables](https://getbootstrap.com/docs/5.3/customize/css-variables/) | ||
| to customize a lot of the colors. | ||
|
|
||
| Here are some of the most common customizations that can be made in the template's | ||
| CSS file `material/public/main.css`, like updating the header color, changing the font, | ||
|
|
||
|
|
||
| ```css | ||
| /* COLOR VARIABLES*/ | ||
| /* Changing the navbar color only for the light theme */ | ||
| [data-bs-theme='light'] nav.navbar { | ||
| background-color: var(--bs-primary-bg-subtle); | ||
| } | ||
|
|
||
| /* Change active navlink color */ | ||
| .navbar-nav .nav-link.active, | ||
| .navbar-nav .nav-link.show { | ||
| color: var(--bs-link-hover-color); | ||
| } | ||
|
|
||
| /* Changing the site font */ | ||
| @import url('https://fonts.googleapis.com/css2?family=Roboto:wght@100;400;700&display=swap'); | ||
|
|
||
| :root { | ||
| --header-bg-color: #0d47a1; | ||
| --header-ft-color: #fff; | ||
| --highlight-light: #5e92f3; | ||
| --highlight-dark: #003c8f; | ||
| --font-color: #34393e; | ||
| ... | ||
| --bs-font-sans-serif: 'Roboto'; | ||
| ... | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| ## Markdown extras | ||
|
|
||
| For more reference about markdown support in DocFX check the | ||
| [official documentation.](https://dotnet.github.io/docfx/docs/markdown.html) | ||
|
|
||
| > [!NOTE] | ||
| > This is a note which needs your attention, but it's not super important. | ||
| > | ||
| > [!WARNING] | ||
| > This is a warning containing some important message. | ||
| > | ||
| > [!CAUTION] | ||
| > This is a warning containing some **very** important message. | ||
| ## DocFX tips | ||
|
|
||
| ### Enable search | ||
|
|
||
| To enable search in DocFX it's not enough to set the configuration parameter to `true`: | ||
|
|
||
| ```json | ||
| "globalMetadata": { | ||
| "_enableSearch": "true" | ||
| } | ||
| ``` | ||
|
|
||
| You also have to indicate in the `docfx.json` the post processor that generates the index for the searches: | ||
|
|
||
| ```json | ||
| "postProcessors": ["ExtractSearchIndex"], | ||
| ``` |
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,71 @@ | ||
| # DocFX Material | ||
|
|
||
| A simple material theme for [DocFX](https://dotnet.github.io/docfx/). This is an | ||
| override of the **default** template so you need to enable both in the `docfx.json`. | ||
|
|
||
| The colors were chosen using <https://material.io/tools/color>. | ||
|
|
||
|  | ||
|
|
||
| ## Install | ||
|
|
||
| 1. Download the source or the zipped file from the [releases](https://github.com/ovasquez/docfx-material/releases). | ||
| 2. Create a `templates` folder in the root of your DocFX directory. | ||
| 3. Copy the `material-classic` folder to the `templates` folder. | ||
| 4. Update the `docfx.json` configuration to include the material template: | ||
| ```json | ||
| { | ||
| "template": [ | ||
| "default", | ||
| "templates/material-classic" | ||
| ], | ||
| } | ||
| ``` | ||
|
|
||
| ## Color customization | ||
|
|
||
| You can easily customize the color of the header bar and the links by updating | ||
| the following variables in the `material-classic/styles/main.css` file. | ||
|
|
||
| ```css | ||
| /* COLOR VARIABLES*/ | ||
| :root { | ||
| --header-bg-color: #0d47a1; | ||
| --header-ft-color: #fff; | ||
| --highlight-light: #5e92f3; | ||
| --highlight-dark: #003c8f; | ||
| --font-color: #34393e; | ||
| } | ||
| ``` | ||
|
|
||
| ## Markdown extras | ||
|
|
||
| For more reference about markdown support in DocFX check the | ||
| [official documentation.](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html?tabs=tabid-1%2Ctabid-a#note-warningtipimportant) | ||
|
|
||
| > [!NOTE] | ||
| > This is a note which needs your attention, but it's not super important. | ||
| > | ||
| > [!WARNING] | ||
| > This is a warning containing some important message. | ||
| > | ||
| > [!CAUTION] | ||
| > This is a warning containing some **very** important message. | ||
| ## DocFX tips | ||
|
|
||
| ### Enable search | ||
|
|
||
| To enable search in DocFX it's not enough to set the configuration parameter to `true`: | ||
|
|
||
| ```json | ||
| "globalMetadata": { | ||
| "_enableSearch": "true" | ||
| } | ||
| ``` | ||
|
|
||
| You also have to indicate in the `docfx.json` the post processor that generates the index for the searches: | ||
|
|
||
| ```json | ||
| "postProcessors": ["ExtractSearchIndex"], | ||
| ``` |
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
File renamed without changes
File renamed without changes
File renamed without changes
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
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
Oops, something went wrong.