Skip to content

Commit fb089d4

Browse files
z9r5z9r5
authored
chore: Update README with usage info and other minor updates (#14)
Signed-off-by: Artem Kladov <artem.kladov@flant.com>
1 parent 778b7c8 commit fb089d4

File tree

5 files changed

+163
-14
lines changed

5 files changed

+163
-14
lines changed

‎README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,89 @@ The Hugo version assumed to be 0.150.1. But it maybe will work with higher versi
2323
1. Use the folder `project_template` as a template for your new Deckhouse product website.
2424
1. Add content in the `content` folder and customize the configuration in the `config` folder.
2525
- Define product name and baseURL the `config/_default/hugo.yaml` file.
26+
27+
## Structure of the content
28+
29+
...coming soon...
30+
31+
## Markup
32+
33+
The project uses [Hugo](gohugo.io) SSG and the [hugo-web-product-module](https://github.com/deckhouse/hugo-web-product-module/) module for a theme.
34+
35+
The documentation content is written in Markdown with some custom shortcodes.
36+
37+
### Page parameters (front matter)
38+
39+
#### Related links
40+
41+
```yaml
42+
params:
43+
relatedLinks:
44+
- title: "Link"
45+
url: link.html
46+
- title: "External link"
47+
url: "http://domain/external/link.html"
48+
- url: /modules/monitoring-kubernetes/
49+
```
50+
51+
### Shortcodes
52+
53+
<div id="alert-details"></div>
54+
55+
#### Alert
56+
57+
There are following levels of alerts: `info`, `warning`, `danger`. The default level is `info`.
58+
59+
```go
60+
{{< alert level="warning" >}}
61+
The warning message...
62+
{{< /alert >}}
63+
```
64+
65+
#### Tabs
66+
67+
```go
68+
{{< tabs >}}
69+
{{% tab "MacOS" %}} # MacOS Content {{% /tab %}}
70+
{{% tab "Linux" %}} # Linux Content {{% /tab %}}
71+
{{% tab "Windows" %}} # Windows Content {{% /tab %}}
72+
{{< /tabs >}}
73+
```
74+
75+
#### Translate
76+
77+
Translates content based on the current language using the translations defined in the `i18n` folder.
78+
79+
```go
80+
{{< translate "version_of_module" >}}
81+
```
82+
83+
<div id="shortcode-details"></div>
84+
85+
#### Details
86+
87+
```go
88+
{{% details "Summary..."%}}
89+
## Markdown content
90+
91+
Markdown content...
92+
{{% /details %}}
93+
```
94+
95+
### Partials
96+
97+
#### Details
98+
99+
The same as the [details shortcode](#user-content-shortcode-details), but used in templates.
100+
101+
```
102+
{{ partial "details" ( dict "summary" "Summary..." "content" "Markdown content..." ) }}
103+
```
104+
105+
#### Alert
106+
107+
The same as the [alert shortcode](#user-content-alert-details), but used in templates.
108+
109+
```
110+
{{ partial "alert" ( dict "level" "warning" "content" "Markdown content..." ) }}
111+
```

‎layouts/_partials/details.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<div class="details">
2+
<p class="details__lnk"><a href="javascript:void(0)" class="details__summary">{{ .summary | markdownify }}</a></p>
3+
<div class="details__content">
4+
<div class="expand">
5+
{{- .content | markdownify }}
6+
</div>
7+
</div>
8+
</div>

‎layouts/_shortcodes/details.html‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{{- $summary := or (.Get "summary") "Details" }}
2+
<div class="details">
3+
<p class="details__lnk"><a href="javascript:void(0)" class="details__summary">{{ $summary | .Page.RenderString }}</a></p>
4+
<div class="details__content">
5+
<div class="expand">
6+
{{ .Inner | .Page.RenderString (dict "display" "block") -}}
7+
</div>
8+
</div>
9+
</div>

‎project_template/.werf/nginx-local.conf‎

Lines changed: 53 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,16 @@ events {
99
}
1010

1111
http {
12+
resolver 127.0.0.11 valid=30s ipv6=off;
13+
resolver_timeout 30s;
1214
proxy_cache_path /cache keys_zone=dcache:10m max_size=200m inactive=30d;
1315

16+
# Global timeout settings
17+
keepalive_timeout 65;
18+
client_body_timeout 60s;
19+
client_header_timeout 60s;
20+
send_timeout 60s;
21+
1422
log_format json_combined escape=json '{ "time_local": "$time_local", '
1523
'"host": "$host", '
1624
'"remote_addr": "$remote_addr", '
@@ -59,6 +67,11 @@ http {
5967
default "deckhouse.ru";
6068
}
6169

70+
map $http_upgrade $connection_upgrade {
71+
default upgrade;
72+
'' close;
73+
}
74+
6275
upstream deckhouse_io {
6376
server deckhouse.io:443;
6477
}
@@ -67,6 +80,16 @@ http {
6780
server deckhouse.ru:443;
6881
}
6982

83+
upstream hugo_1313 {
84+
zone hugo_1313 64k;
85+
server hugo:1313 resolve max_fails=0;
86+
}
87+
88+
upstream hugo_1314 {
89+
zone hugo_1314 64k;
90+
server hugo:1314 resolve max_fails=0;
91+
}
92+
7093
server {
7194
root /app;
7295
index index.html;
@@ -78,7 +101,7 @@ http {
78101
set_real_ip_from 0.0.0.0/0;
79102
access_log /dev/stdout json_combined;
80103
error_log /dev/stderr debug;
81-
error_page 403 404 /products/<PRODUCT>/documentation/404/;
104+
error_page 403 404 /products/<PRODUCT_LOCATION_PART>/documentation/404/;
82105

83106
location = /search.json {
84107
return 200 "[]";
@@ -101,27 +124,46 @@ http {
101124
proxy_pass $publicdocupstream;
102125
}
103126

104-
location ~* /products/prompp/(livereload|documentation/).*$ {
127+
# Specific location for livereload WebSocket endpoint
128+
location ~* ^.*/(livereload|livereload\.js) {
129+
# Don't retry WebSocket connections - they can't be retried
130+
proxy_next_upstream off;
131+
proxy_next_upstream_timeout 0;
132+
proxy_next_upstream_tries 1;
133+
105134
proxy_redirect off;
106-
proxy_intercept_errors on;
135+
proxy_intercept_errors off;
107136
proxy_set_header Host $host;
108137
proxy_set_header X-Real-IP $remote_addr;
109138
proxy_set_header X-Original-URI $request_uri;
110139
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
111140

112-
# WebSocket support for livereload
141+
proxy_connect_timeout 10s;
142+
proxy_send_timeout 3600s;
143+
proxy_read_timeout 3600s;
144+
145+
proxy_buffering off;
146+
proxy_request_buffering off;
147+
148+
# WebSocket support - ensure proper headers
113149
proxy_http_version 1.1;
114150
proxy_set_header Upgrade $http_upgrade;
115-
proxy_set_header Connection "upgrade";
151+
proxy_set_header Connection $connection_upgrade;
152+
proxy_set_header X-Forwarded-Proto $scheme;
153+
proxy_set_header X-Forwarded-Host $host;
116154

117155
proxy_pass http://$hugo_upstream;
118156
}
119-
}
120-
upstream hugo_1313 {
121-
server hugo:1313;
122-
}
123157

124-
upstream hugo_1314 {
125-
server hugo:1314;
158+
location ~* ^/products/<PRODUCT_LOCATION_PART>/documentation/.*$ {
159+
proxy_redirect off;
160+
proxy_intercept_errors on;
161+
proxy_set_header Host $host;
162+
proxy_set_header X-Real-IP $remote_addr;
163+
proxy_set_header X-Original-URI $request_uri;
164+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
165+
166+
proxy_pass http://$hugo_upstream;
167+
}
126168
}
127169
}

‎project_template/README.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# Deckhouse <PRODUCT_NAME> documentation
22

3-
This is the source for the Deckhouse <PRODUCT_NAME> documentation website.
3+
This is the source for the Deckhouse <PRODUCT_NAME> documentation website.
4+
5+
The project uses [Hugo](gohugo.io) SSG and the [hugo-web-product-module](https://github.com/deckhouse/hugo-web-product-module/) module for a theme (see [README.md](https://github.com/deckhouse/hugo-web-product-module/blob/main/README.md) for details about content markup).
6+
7+
Read [`hugo-web-product-module` README.md](https://github.com/deckhouse/hugo-web-product-module/blob/main/README.md) for information about content markup and other details.
8+
9+
## How to run the documentation site locally
410

511
To run locally:
612
1. Install werf and docker.
@@ -11,5 +17,3 @@ To run locally:
1117
```
1218

1319
1. Open `http://localhost/products/<PRODUCT_CODE>/documentation/` in your browser (for the english version) or `http://ru.localhost/products/<PRODUCT_CODE>/documentation/` (for the russian version).
14-
15-
The project uses the [hugo-web-product-module](https://github.com/deckhouse/hugo-web-product-module).

0 commit comments

Comments
 (0)