Skip to content

Commit 33860a5

Browse files
nojafnojaf
committed
Add documentation about CSS styling.
1 parent 02bebbd commit 33860a5

File tree

3 files changed

+103
-56
lines changed

3 files changed

+103
-56
lines changed

‎RELEASE_NOTES.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
### Removed
99
- `--fsdocs-theme-toggle-light-color` and `--fsdocs-theme-toggle-dark-color` are now deprecated. Use `--header-link-color` instead.
10+
- `<FsDocsCollectionNameLink>`
1011

1112
## 20.0.0-alpha-012 - 2023-11-17
1213

‎docs/_template.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
{{fsdocs-list-of-namespaces}}
3737
</ul>
3838
</div>
39-
<a href="{{root}}">
39+
<a href="{{fsdocs-logo-link}}">
4040
<img alt="Header menu logo" src="{{root}}{{fsdocs-logo-src}}">
4141
<strong>{{fsdocs-collection-name}}</strong>
4242
</a>

‎docs/styling.md‎

Lines changed: 101 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,17 @@ category: Documentation
33
categoryindex: 1
44
index: 7
55
---
6-
# Customization and Styling
6+
7+
# Customization and Styling
78

89
When using `fsdocs`, there are six levels of extra content development and styling.
910

10-
1. Don't do any styling or documentation customization and simply write content. This is by far the simplest option to maintain.
11+
1. Don't do any styling or documentation customization and simply write content. This is by far the simplest option to
12+
maintain.
1113

1214
2. Add content such as an `docs/index.md` to customize the front-page content for your generated docs.
1315
You can also add content such as `docs/reference/fslib.md` to give a bespoke landing page
14-
for one of your namespaces, e.g. here assumed to be `namespace FsLib`. This will override any
16+
for one of your namespaces, e.g. here assumed to be `namespace FsLib`. This will override any
1517
generated content.
1618

1719
3. Customize via Styling Parameters
@@ -22,13 +24,17 @@ When using `fsdocs`, there are six levels of extra content development and styli
2224

2325
6. Customize by generating your own site using your own code
2426

25-
By default `fsdocs` does no styling customization and uses the following defaults. These are the settings used to build this site.
27+
By default `fsdocs` does no styling customization and uses the following defaults. These are the settings used to build
28+
this site.
2629

27-
* Uses the default template in [docs/_template.html](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/_template.html)
30+
* Uses the default template
31+
in [docs/_template.html](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/_template.html)
2832

29-
* Uses the default styles in [docs/content/fsdocs-default.css](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/content/fsdocs-default.css).
33+
* Uses the default styles
34+
in [docs/content/fsdocs-default.css](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/content/fsdocs-default.css).
3035

31-
* Uses no custom styles in [docs/content/fsdocs-custom.css](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/content/fsdocs-default.css).
36+
* Uses no custom styles
37+
in [docs/content/fsdocs-custom.css](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/content/fsdocs-default.css).
3238

3339
* Uses no styling parameters except those extracted from the project files.
3440

@@ -39,75 +45,108 @@ you adjust them there is no guarantee that your template will continue to work w
3945

4046
The following [content parameters](content.html) are particularly related to visual styling:
4147

42-
| Substitution name | Value (if not overriden by --parameters) |
43-
|:------------------------------------|:--------------------------------------------------------------|
44-
| `fsdocs-authors` | `<Authors>` |
45-
| `fsdocs-collection-name-link` | `<FsDocsCollectionNameLink>` |
46-
| `fsdocs-license-link` | `<FsDocsLicenseLink>` |
47-
| `fsdocs-logo-src` | `<FsDocsLogoSource>` |
48-
| `fsdocs-logo-link` | `<FsDocsLogoLink>` |
49-
| `fsdocs-release-notes-link` | `<FsDocsReleaseNotesLink>` else `<PackageProjectUrl>/blob/master/RELEASE_NOTES.md` |
50-
| `fsdocs-repository-link` | `<RepositoryUrl>` |
51-
| `fsdocs-theme` | `<FsDocsTheme>`, must currently be `default` |
48+
| Substitution name | Value (if not overriden by --parameters) |
49+
|:----------------------------|:-----------------------------------------------------------------------------------|
50+
| `fsdocs-authors` | `<Authors>` |
51+
| `fsdocs-license-link` | `<FsDocsLicenseLink>` |
52+
| `fsdocs-logo-src` | `<FsDocsLogoSource>` |
53+
| `fsdocs-favicon-src` | `<FsDocsFaviconSource>` |
54+
| `fsdocs-logo-link` | `<FsDocsLogoLink>` |
55+
| `fsdocs-release-notes-link` | `<FsDocsReleaseNotesLink>` else `<PackageProjectUrl>/blob/master/RELEASE_NOTES.md` |
56+
| `fsdocs-repository-link` | `<RepositoryUrl>` |
57+
| `fsdocs-theme` | `<FsDocsTheme>`, must currently be `default` |
5258

5359
These basic entry-level styling parameters can be set in the project file or `Directory.Build.props`.
5460
For example:
5561

5662
```xml
63+
64+
<PropertyGroup>
5765
<!-- Example ultra-simple styling and generation settings for FsDocs default template-->
5866
<PackageLicenseUrl>https://github.com/foo/bar/blob/master/License.txt</PackageLicenseUrl>
5967
<PackageProjectUrl>https://foo.github.io/bar/</PackageProjectUrl>
6068
<RepositoryUrl>https://github.com/foo/bar/</RepositoryUrl>
6169
<FsDocsLogoLink>https://fsharp.org</FsDocsLogoLink>
70+
<FsDocsLogoSource>img/logo.png</FsDocsLogoSource>
71+
<FsDocsFaviconSource>img/favicon.ico</FsDocsFaviconSource>
6272
<FsDocsLicenseLink>https://github.com/foo/bar/blob/master/License.txt</FsDocsLicenseLink>
6373
<FsDocsReleaseNotesLink>https://github.com/foo/bar/blob/master/release-notes.md</FsDocsReleaseNotesLink>
6474
<FsDocsWarnOnMissingDocs>true</FsDocsWarnOnMissingDocs>
6575
<FsDocsTheme>default</FsDocsTheme>
76+
</PropertyGroup>
6677
```
6778

68-
As an example, here is [a page with `fsdocs-navbar-position` set to `fixed-right`](templates/leftside/styling.html).
79+
As an example, here is [a page with alternative styling](templates/leftside/styling.html).
6980

7081
## Customizing via CSS
7182

72-
You can start styling by creating a file `docs/content/fsdocs-custom.css` and adding entries to it. It is loaded by
73-
the standard template. The CSS classes of generated content are:
74-
75-
| CSS class | Corresponding Content|
76-
|:------------------------------------|:--------------------------------------------------------------|
77-
| `.fsdocs-tip` | generated tooltips |
78-
| `.fsdocs-xmldoc` | generated xmldoc sections |
79-
| `.fsdocs-member-list` | generated member lists (tables) |
80-
| `.fsdocs-member-usage` | usage in generated member lists |
81-
| `.fsdocs-member-tooltip` | tooltips in generated member lists |
82-
| `.fsdocs-member-xmldoc` | documentation in generated member lists |
83-
| `.fsdocs-entity-list` | generated entity lists |
84-
| `.fsdocs-entity-name` | generated entity lists |
85-
| `.fsdocs-entity-xmldoc` | documentation in generated entity lists |
86-
| `.fsdocs-exception-list` | generated exception lists |
87-
| `.fsdocs-summary` | the 'summary' section of an XML doc |
88-
| `.fsdocs-remarks` | the 'remarks' section of an XML doc |
89-
| `.fsdocs-params` | the 'parameters' section of an XML doc |
90-
| `.fsdocs-param` | a 'parameter' section of an XML doc |
91-
| `.fsdocs-param-name` | a 'parameter' name of an XML doc |
92-
| `.fsdocs-returns` | the 'returns' section of an XML doc |
93-
| `.fsdocs-example` | the 'example' section of an XML doc |
94-
| `.fsdocs-note` | the 'notes' section of an XML doc |
95-
| `.fsdocs-para` | a paragraph of an XML doc |
83+
You can start styling by creating a file `docs/content/fsdocs-theme.css` and adding entries to it.
84+
It is loaded by the standard template.
85+
86+
### CSS variables
87+
88+
The default template is heavily based
89+
on [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). These can easily be
90+
override to customize the look and feel of the default theme.
91+
A full list of the overrideable variables can be
92+
found [here](https://github.com/fsprojects/FSharp.Formatting/blob/main/docs/content/fsdocs-theme.css).
93+
94+
```css
95+
:root {
96+
--text-color: red;
97+
}
98+
99+
[data-theme=dark] {
100+
--text-color: darkred;
101+
}
102+
```
103+
104+
Please be aware that the `dark` mode in the default theme is using the same variables.
105+
When you override a variable, it will also be used in `dark` mode unless redefined in a `[data-theme=dark]` CSS query.
106+
107+
### CSS classes
108+
109+
The API documentation uses a set of fixed CSS classes:
110+
111+
| CSS class | Corresponding Content |
112+
|:-------------------------|:----------------------------------------|
113+
| `.fsdocs-tip` | generated tooltips |
114+
| `.fsdocs-xmldoc` | generated xmldoc sections |
115+
| `.fsdocs-member-list` | generated member lists (tables) |
116+
| `.fsdocs-member-usage` | usage in generated member lists |
117+
| `.fsdocs-member-tooltip` | tooltips in generated member lists |
118+
| `.fsdocs-member-xmldoc` | documentation in generated member lists |
119+
| `.fsdocs-entity-list` | generated entity lists |
120+
| `.fsdocs-entity-name` | generated entity lists |
121+
| `.fsdocs-entity-xmldoc` | documentation in generated entity lists |
122+
| `.fsdocs-exception-list` | generated exception lists |
123+
| `.fsdocs-summary` | the 'summary' section of an XML doc |
124+
| `.fsdocs-remarks` | the 'remarks' section of an XML doc |
125+
| `.fsdocs-params` | the 'parameters' section of an XML doc |
126+
| `.fsdocs-param` | a 'parameter' section of an XML doc |
127+
| `.fsdocs-param-name` | a 'parameter' name of an XML doc |
128+
| `.fsdocs-returns` | the 'returns' section of an XML doc |
129+
| `.fsdocs-example` | the 'example' section of an XML doc |
130+
| `.fsdocs-note` | the 'notes' section of an XML doc |
131+
| `.fsdocs-para` | a paragraph of an XML doc |
96132

97133
Some generated elements are given specific HTML ids:
98134

99-
| HTML Element Id | Content|
100-
|:------------------------------------|:--------------------------------------------------------------|
101-
| `#fsdocs-content` | The generated content |
102-
| `#fsdocs-searchbox ` | The search box |
103-
| `#fsdocs-logo ` | The logo |
104-
| `#fsdocs-nav ` | The navigation-bar |
135+
| HTML element selector | Content |
136+
|:----------------------------|:-------------------------------|
137+
| `header` | The navigation-bar |
138+
| `#fsdocs-main-menu` | The main menu on the left side |
139+
| `#content` | The generated content |
140+
| `#fsdocs-page-menu` | The sub menu on the right side |
141+
| `dialog` | The search dialog |
142+
| `dialog input[type=search]` | The search box |
143+
| `#fsdocs-logo ` | The logo |
105144

106145
If you write a new theme by CSS styling please contribute it back to FSharp.Formatting.
107146

108147
## Customizing via a new template
109148

110-
You can do advanced styling by creating a new template. Add a file `docs/_template.html`, likely starting
149+
You can do advanced styling by creating a new template. Add a file `docs/_template.html`, likely starting
111150
with the existing default template.
112151

113152
> NOTE: To enable hot reload during development with `fsdocs watch` in a custom `_template.html` file,
@@ -124,6 +163,7 @@ You can add advanced styling to the sidebar generated menu items by creating a n
124163
To customize the generated menu-item headers, use file `_menu_template.html` with starting template:
125164

126165
```html
166+
127167
<li class="nav-header">
128168
{{fsdocs-menu-header-content}}
129169
</li>
@@ -133,26 +173,32 @@ To customize the generated menu-item headers, use file `_menu_template.html` wit
133173
Similarly, to customize the individual menu item list, use file `_menu-item_template.html` with starting template:
134174

135175
```html
176+
136177
<li class="nav-item"><a href="{{fsdocs-menu-item-link}}" class="nav-link">{{fsdocs-menu-item-content}}</a></li>
137178
```
179+
138180
Do note that files need to be added prior running or won't be generated.
139-
In case you want to get a unique identifier for a header or menu item, you can use `{{fsdocs-menu-header-id}}` and `{{fsdocs-menu-item-id}}`, respectively.
181+
In case you want to get a unique identifier for a header or menu item, you can use `{{fsdocs-menu-header-id}}`
182+
and `{{fsdocs-menu-item-id}}`, respectively.
140183

141184
## Injecting additional html into the default template
142185

143-
Occasionally, you may find the need to make small customizations to the default template, such as adding a Google Analytics snippet or including additional style or script tags. To address this scenario, you can create two files: `_head.html` and/or `_body.html`.
186+
Occasionally, you may find the need to make small customizations to the default template, such as adding a Google
187+
Analytics snippet or including additional style or script tags. To address this scenario, you can create two
188+
files: `_head.html` and/or `_body.html`.
144189

145-
The content within these files will serve as replacements for the `{{fsdocs-head-extra}}` and `{{fsdocs-body-extra}}` placeholders, which are utilized in the default template.
190+
The content within these files will serve as replacements for the `{{fsdocs-head-extra}}` and `{{fsdocs-body-extra}}`
191+
placeholders, which are utilized in the default template.
146192

147193
## Customizing by generating your own site using your own code
148194

149195
The `FSharp.Formatting.ApiDocs` namespace includes a `GenerateModel` that captures
150-
the results of documentation preparation in `ApiDocsModel` and allows you to
196+
the results of documentation preparation in `ApiDocsModel` and allows you to
151197
generate your own site using your own code.
152198

153-
> NOTE: The ApiDocsModel API is undergoing change and improvement and there is no guarantee that your bespoke site generation will continue to work
199+
> NOTE: The ApiDocsModel API is undergoing change and improvement and there is no guarantee that your bespoke site
200+
> generation will continue to work
154201
> with future versions of F# Formatting.
155202
156203
> NOTE: The `ApiDocsModel` currently includes some generated HTML with some specific style tags.
157204
> In the long term these may be removed from the design of that component.
158-

0 commit comments

Comments
 (0)