Skip to content

Commit a368fdb

Browse files
authored
Merge pull request #489 from zihanKuang/fix-large-size
docs: improve image customization guidance and clean up broken links
2 parents 777f1bb + b43ba3a commit a368fdb

File tree

1 file changed

+33
-33
lines changed

1 file changed

+33
-33
lines changed

content/en/kanvas/reference/contributing-to-docs.md

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
---
2-
title: Contributing to Docs
2+
title: Contributing to Layer5 Docs
33
weight: 10
44
description: A detailed contribution guide for Layer5 Docs.
55
aliases:
66
- /meshmap/reference/contributing-to-docs
77
---
8-
## Contributing to the docs.layer5.io Website
98

109
Welcome to the GitHub repository for Layer5's documentation website!
1110

@@ -143,48 +142,50 @@ git -C themes/docsy checkout tags/v0.6.0
143142

144143
## Documentation style guide
145144

146-
For guidance on writing effective documentation, see
147-
the style guide for the Layer5 docs.
145+
For guidance on writing effective documentation, see the style guide for the Layer5 docs.
148146

149-
## Styling your content
147+
### Overriding theme styles
150148

151149
The theme holds its styles in the [`assets/scss` directory](https://github.com/layer5io/docs/tree/master/assets/scss).
152150

153-
**Do not change these files**, they are not actually inside this repo, but are part of the [google/docsy](https://github.com/google/docsy) repo.
151+
**Do not change these files**, they are not actually inside this repo, but are part of the [google/docsy](https://github.com/google/docsy) repo. These files are managed as a Git submodule and may be updated or replaced when the theme is upgraded. Any changes made directly to the theme files will be lost during updates and are not preserved in version control.
154152

155153
You can override the default styles and add new ones:
156154

157-
* In general, put your files in the project directory structure under `website` rather than in the theme directory.
158-
Use the same file name as the theme does, and put the file in the same relative position.
159-
Hugo looks first at the file in the main project directories, if present, then at the files under the theme directory.
160-
For example, the Layer5 website's [`layouts/partials/navbar.html`](https://github.com/layer5io/docs/blob/master/layouts/partials/navbar.html)
161-
overrides the theme's [`layouts/partials/navbar.html`](https://github.com/layer5io/docs/blob/master/themes/docsy/layouts/partials/navbar.html)
162-
163-
* You can update the Layer5 website's project variables in the [`_variables_project.scss` file](https://github.com/layer5io/docs/blob/master/assets/scss/_variables_project.scss).
164-
Values in that file override the [Docsy variables](https://github.com/layer5io/docs/blob/master/themes/docsy/assets/scss/_variables.scss).
165-
You can also use `_variables_project.scss` to specify your own values for any of the default [Bootstrap 4 variables](https://getbootstrap.com/docs/4.0/getting-started/theming/).
166-
167-
* Custom styles [`_styles_project` file](https://github.com/layer5io/docs/blob/master/assets/scss/_styles_project.scss)
168-
169-
Styling of images:
170-
171-
* To see some examples of styled images, take a look at the OAuth setup page in the Layer5 docs.
172-
Search for `.png` in the [page source](https://raw.githubusercontent.com/layer5io/docs/master/content/en/docs/gke/deploy/oauth-setup.md).
155+
* To override templates or layouts, place your files in the main project directory (e.g., `layouts/partials/`) instead of editing the theme files under `themes/docsy/`.
156+
* Use the same file name and relative path as the theme. Hugo will look for files in the project first and fall back to the theme if no override is found.
157+
158+
For example, to override the theme’s navigation bar template:
159+
```
160+
Project override: layouts/partials/navbar.html
161+
Theme default: themes/docsy/layouts/partials/navbar.html
162+
```
163+
* To customize SCSS variables, update the `_variables_project.scss` file in the `assets/scss/` directory. This file overrides the theme’s SCSS variables and can also be used to redefine Bootstrap variables.
164+
* For adding custom CSS rules, use the `_styles_project.scss` file in the same `assets/scss/` directory.
173165

174-
* For more help, see the guide to
175-
[Bootstrap image styling](https://getbootstrap.com/docs/4.0/content/images/).
166+
### Image styling
176167

177-
* Also see the Bootstrap utilities, such as
178-
[borders](https://getbootstrap.com/docs/4.0/utilities/borders/).
168+
By default, Markdown images are written like this:
169+
```markdown
170+
![Alt text](/path/to/image.png)
171+
```
172+
These are rendered with:
173+
- `max-width: 70%` of the viewport
174+
- `max-height: 80vh` of the viewport height
175+
- centered block layout
179176

180-
The site's [front page](https://docs.layer5.io/):
177+
This default styling works well for most landscape (horizontal) images. However, if an image is very tall, narrow, or otherwise looks awkward, you can override the default by embedding raw HTML and specifying a custom size:
181178

182-
* See the [page source](https://github.com/layer5io/docs/blob/master/content/en/).
183-
* The CSS styles are in the [project variables file](https://github.com/layer5io/docs/blob/master/assets/scss/_variables_project.scss).
179+
```html
180+
<img src="./images/example.png" alt="Example description" style="max-width: 40vw; max-height: 60vh; display: block; margin: 1rem auto;" />
181+
```
184182

185-
* The page uses the [cover block](https://www.docsy.dev/docs/adding-content/shortcodes/#blocks-cover) defined by the theme.
183+
### Additional resources
186184

187-
* The page also uses the [linkdown block](https://www.docsy.dev/docs/adding-content/shortcodes/#blocks-link-down).
185+
- **Bootstrap image utilities:**
186+
https://getbootstrap.com/docs/4.0/content/images/
187+
- **Bootstrap utilities (borders, floats, etc.):**
188+
https://getbootstrap.com/docs/4.0/utilities/
188189

189190
## Using Hugo shortcodes
190191

@@ -247,7 +248,7 @@ Useful Hugo docs:
247248
## Versioning of the docs
248249
249250
For each stable release, we create a new branch for the relevant documentation.
250-
For example, the documentation for the v0.2 stable release is maintained in the [v0.2-branch](https://github.com/layer5io/docs/tree/v0.2-branch).
251+
For example, the documentation for the v0.2 stable release is maintained in the `v0.2-branch`.
251252
Each branch has a corresponding Netlify website that automatically syncs each merged PR.
252253
253254
The versioned sites follow this convention:
@@ -257,7 +258,6 @@ The versioned sites follow this convention:
257258
* `vXXX-YYY.docs.layer5.io` points to the release at vXXX.YYY-branch
258259
259260
We also hook up each version to the dropdown on the website menu bar.
260-
For information on how to update the website to a new version, see the [Layer5 release guide](https://github.com/layer5io/docs/blob/master/docs_dev/releasing.md#releasing-a-new-version-of-the-website).
261261
262262
Whenever any documents reference any source code, you should use the version shortcode in the links, like so:
263263

0 commit comments

Comments
 (0)