Skip to content

Commit b02b40a

Browse files
aabidsofi19aabidsofi19
committed
add tenant scoped shortcodes
Signed-off-by: Aabid Sofi <mailtoaabid01@gmail.com>
1 parent 276c7bf commit b02b40a

3 files changed

Lines changed: 68 additions & 163 deletions

File tree

‎README.md‎

Lines changed: 36 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -1,187 +1,60 @@
1-
# Docsy Example
1+
Reusable hugo theme module that powers the layer5 academy .
2+
this modules provides the layouts , shortcodes and partials to get academy up and running
23

3-
[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy
4-
site navigation, structure, and more. This **Docsy Example Project** uses the Docsy
5-
theme component as a hugo module and provides a skeleton documentation structure for you to use.
6-
You can clone/copy this project and edit it with your own content, or use it as an example.
4+
The recommended approach to use this theme is through the academy starter template .
75

8-
In this project, the Docsy theme is pulled in as a Hugo module, together with
9-
its dependencies:
6+
## Getting started with this theme
107

11-
```console
12-
$ hugo mod graph
13-
...
14-
```
15-
16-
For Docsy documentation, see [Docsy user guide][].
17-
18-
This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][].
19-
You can view deploy logs from the [deploy section of the project's Netlify
20-
dashboard][deploys], or this [alternate dashboard][].
21-
22-
This is not an officially supported Google product. This project is currently maintained.
23-
24-
## Using the Docsy Example Project as a template
25-
26-
A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this:
27-
28-
1. Use the dropdown for switching branches/tags to change to the **latest** released tag.
29-
30-
2. Click **Use this template**.
31-
32-
3. Select a name for your new project and click **Create repository from template**.
33-
34-
4. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL:
35-
36-
```bash
37-
git clone --depth 1 https://github.com/me/example.git
38-
```
39-
40-
Depending on your environment you may need to adjust the top-level `module` settings in your project's Hugo config file, for example, by adding a proxy to use when downloading remote modules.
41-
You can find details of what these configuration settings do in the [Hugo modules documentation](https://gohugo.io/hugo-modules/configuration/#module-config-top-level).
42-
43-
Once your settings are adjusted, you can edit your own versions of the site’s source files.
44-
45-
If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
46-
47-
```bash
48-
npm install
49-
```
50-
51-
## Running the website locally
52-
53-
Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
54-
You can find out more about how to install Hugo for your environment in our
55-
[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
56-
57-
Once you've made your working copy of the site repo, from the repo root folder, run:
58-
59-
```bash
60-
hugo server
61-
```
62-
63-
## Running a container locally
64-
65-
You can run docsy-example inside a [Docker](https://docs.docker.com/)
66-
container, the container runs with a volume bound to the `docsy-example`
67-
folder. This approach doesn't require you to install any dependencies other
68-
than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
69-
Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
70-
on Linux.
718

72-
1. Build the docker image
9+
The recommended approach to use this theme is through the academy starter template .
7310

74-
```bash
75-
docker-compose build
76-
```
7711

78-
1. Run the built image
12+
## 📄 `tenant-context.html` (Required Partial)
7913

80-
```bash
81-
docker-compose up
82-
```
14+
**Location:** `layouts/partials/tenant-context.html`
15+
**Purpose:** Provides a hardcoded tenant UUID (`orgId`) for shortcodes and templates to use. This enables tenant-aware content in a multi-tenant Hugo theme.
8316

84-
> NOTE: You can run both commands at once with `docker-compose up --build`.
17+
---
8518

86-
1. Verify that the service is working.
19+
### 📌 Why this is required
8720

88-
Open your web browser and type `http://localhost:1313` in your navigation bar,
89-
This opens a local instance of the docsy-example homepage. You can now make
90-
changes to the docsy example and those changes will immediately show up in your
91-
browser after you save.
21+
This partial is **mandatory** when using this theme. Many of the theme’s built-in shortcodes (`usestatic`, `useshortcode`, etc.) internally depend on this file to fetch the correct tenant UUID.
9222

93-
### Cleanup
23+
Each tenant must **hardcode their own UUID** in this file to properly namespace assets, shortcodes, and logic.
9424

95-
To stop Docker Compose, on your terminal window, press **Ctrl + C**.
9625

97-
To remove the produced images run:
26+
```gohtml
27+
{{/*
28+
Partial: tenant-context
29+
Required by: usestatic, useshortcode, and other reusable shortcodes.
30+
Description:
31+
Hardcoded context for the current tenant.
32+
This file must be customized per tenant site to return the correct UUID/orgId.
9833
99-
```bash
100-
docker-compose rm
101-
```
102-
For more information see the [Docker Compose documentation][].
103-
104-
## Using a local Docsy clone
105-
106-
Make sure your installed go version is `1.18` or higher.
107-
108-
Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your site's root folder.
109-
110-
```shell
111-
cd root-of-your-site
112-
git clone --branch v0.12.0 https://github.com/google/docsy.git ../docsy
113-
```
114-
115-
Now run:
116-
117-
```shell
118-
HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**"
119-
```
120-
121-
or, when using npm, prepend `local` to the script you want to invoke, e.g.:
122-
123-
```shell
124-
npm run local serve
125-
```
34+
Usage in shortcodes or templates:
35+
{{ $ctx := partial "tenant-context.html" . }}
36+
{{ $uuid := $ctx.uuid }}
37+
*/}}
12638
127-
By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix `local` when using npm), the server now watches all files and directories inside the sibling directory `../docsy` , too. Any changes inside the local `docsy` theme clone are now immediately picked up (hot reload), you can instantly see the effect of your local edits.
128-
129-
In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` to tell hugo about the local workspace file `docsy.work`. Alternatively, you can declare the workspace file inside your settings file `hugo.toml`:
130-
131-
```toml
132-
[module]
133-
workspace = "docsy.work"
134-
```
135-
136-
Your project's `hugo.toml` file already contains these lines, the directive for workspace assignment is commented out, however. Remove the two trailing comment characters '//' so that this line takes effect.
137-
138-
## Troubleshooting
139-
140-
As you run the website locally, you may run into the following error:
141-
142-
```console
143-
$ hugo server
144-
WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information.
145-
Start building sites …
146-
hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio
147-
Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
148-
Built in 27 ms
39+
{{- dict "uuid" "123e4567-e89b-12d3-a456-426614174000" -}}
14940
```
15041

151-
This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.12.0`, hugo version `0.146.0` or higher is required.
152-
See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
153-
154-
Or you may be confronted with the following error:
155-
156-
```console
157-
$ hugo server
42+
> 🔐 Replace `"123e4567-e89b-12d3-a456-426614174000"` with your actual tenant UUID.
15843
159-
INFO 2021/01/21 21:07:55 Using config file:
160-
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
161-
Built in 288 ms
162-
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
163-
```
164-
165-
This error occurs if you have not installed the extended version of Hugo.
166-
See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
44+
---
16745

168-
Or you may encounter the following error:
46+
### 🔁 Used By
16947

170-
```console
171-
$ hugo server
48+
| Theme Shortcode | Purpose |
49+
| --------------- | -------------------------------------- |
50+
| `usestatic` | Resolves static asset paths per tenant |
51+
| `useshortcode` | Renders tenant-specific shortcodes |
52+
| Others | Custom logic scoped by tenant |
17253

173-
Error: failed to download modules: binary with name "go" not found
174-
```
54+
---
17555

176-
This error occurs if the `go` programming language is not available on your system.
177-
See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
56+
### 🚨 Required per Tenant
17857

58+
Each tenant site **must define** this file in their local `layouts/partials/` directory. Without it, most tenant-aware theme features will not work.
17959

180-
[alternate dashboard]: https://app.netlify.com/sites/Layer5 Academy/deploys
181-
[deploys]: https://app.netlify.com/sites/docsy-example/deploys
182-
[Docsy user guide]: https://docsy.dev/docs
183-
[Docsy]: https://github.com/google/docsy
184-
[example.docsy.dev]: https://example.docsy.dev
185-
[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
186-
[Netlify]: https://netlify.com
187-
[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/
60+
---

‎layouts/shortcodes/useshortcode.html‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{{/*
2+
Shortcode: useshortcode
3+
Description: Dynamically includes a shortcode from layouts/shortcodes/uuid/<name>.html with tenant context.
4+
Usage: {{< useshortcode "banner" title="Hello" content="Welcome!" >}}
5+
Notes: Automatically injects `uuid` as a parameter.
6+
*/}}
7+
{{- $ctx := partial "tenant-context.html" . -}}
8+
{{- $uuid := $ctx.uuid -}}
9+
10+
{{- $name := .Get 0 -}}
11+
{{- $params := dict -}}
12+
13+
{{- range $k, $v := .Params -}}
14+
{{- if ne $k "0" -}}
15+
{{- $params = merge $params (dict $k $v) -}}
16+
{{- end -}}
17+
{{- end -}}
18+
19+
{{- $params = merge $params (dict "uuid" $uuid) -}}
20+
21+
{{- partial (printf "shortcodes/uuid/%s.html" $name) $params -}}

‎layouts/shortcodes/usestatic.html‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{{/*
2+
Shortcode: usestatic
3+
Description: Resolves the path to a static asset within the current tenant's UUID scope.
4+
Usage: {{< usestatic "images/logo.png" >}}
5+
Output: /static/<uuid>/images/logo.png
6+
*/}}
7+
8+
{{- $ctx := partial "tenant-context.html" . -}}
9+
{{- $uuid := $ctx.uuid -}}
10+
{{- $path := .Get 0 -}}
11+
{{- printf "/static/%s/%s" $uuid $path | relURL -}}

0 commit comments

Comments
 (0)