@nera-static/plugin-canonical-links 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +142 -0
  3. package/config/canonical-links.yaml +6 -0
  4. package/index.js +62 -0
  5. package/package.json +50 -0
  6. package/views/index.pug +2 -0
  7. package/views/partials/alternate-links.pug +3 -0
  8. package/views/partials/canonical-link.pug +2 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) [2025] [Michael Becker]
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,142 @@
1
+ # @nera-static/plugin-canonical-links
2
+
3
+ A plugin for the [Nera](https://github.com/seebaermichi/nera) static site generator to generate canonical and alternate `<link>` tags for SEO in the document `<head>`. Helps search engines correctly index content across domains and languages.
4
+
5
+ ## ✨ Features
6
+
7
+ - Adds `<link rel="canonical">` for SEO
8
+ - Supports multilingual alternate links
9
+ - Easy Pug template integration
10
+ - Configurable origin and slug mapping
11
+
12
+ ## πŸš€ Installation
13
+
14
+ Install the plugin in the root of your Nera project:
15
+
16
+ ```bash
17
+ npm install @nera-static/plugin-canonical-links
18
+ ```
19
+
20
+ Then create a config file in your project’s `config/` directory:
21
+
22
+ ```
23
+ config/
24
+ └── canonical-links.yaml
25
+ ```
26
+
27
+ Nera will automatically detect the plugin and apply it during the build.
28
+
29
+ ## βš™οΈ Configuration
30
+
31
+ Create `config/canonical-links.yaml`:
32
+
33
+ ```yaml
34
+ app_origin: https://your-domain.com
35
+ page_identifier: slug
36
+ available_languages:
37
+ - en
38
+ - es
39
+ - fr
40
+ ```
41
+
42
+ - `app_origin`: The canonical base URL (overrides `app.origin`).
43
+ - `page_identifier`: Shared key to match localized versions (defaults to `slug`).
44
+ - `available_languages`: List of supported language codes (used to create alternate links).
45
+
46
+ ## πŸ“„ Usage in Templates
47
+
48
+ Include the plugin’s view in your layout head:
49
+
50
+ ```pug
51
+ head
52
+ include /node_modules/@nera-static/plugin-canonical-links/views/index
53
+ ```
54
+
55
+ This will generate:
56
+
57
+ ```html
58
+ <link href="https://example.com/index.html" rel="canonical" />
59
+ <link href="https://example.com/es/index.html" hreflang="es" rel="alternate" />
60
+ <link href="https://example.com/fr/index.html" hreflang="fr" rel="alternate" />
61
+ ```
62
+
63
+ ## πŸ—‚οΈ Content Structure
64
+
65
+ To use alternate links, provide a shared identifier (e.g., `slug`) across translations:
66
+
67
+ ```
68
+ pages/
69
+ β”œβ”€β”€ index.md
70
+ β”œβ”€β”€ es/
71
+ β”‚ └── index.md
72
+ └── fr/
73
+ └── index.md
74
+ ```
75
+
76
+ Example frontmatter for each:
77
+
78
+ **pages/index.md**
79
+
80
+ ```yaml
81
+ lang: en
82
+ slug: home
83
+ ```
84
+
85
+ **pages/es/index.md**
86
+
87
+ ```yaml
88
+ lang: es
89
+ slug: home
90
+ ```
91
+
92
+ **pages/fr/index.md**
93
+
94
+ ```yaml
95
+ lang: fr
96
+ slug: home
97
+ ```
98
+
99
+ ## 🧩 Rendering Details
100
+
101
+ The plugin provides a view file that includes two partials:
102
+
103
+ - `views/index.pug`
104
+
105
+ ```pug
106
+ include partials/canonical-link
107
+ include partials/alternate-links
108
+ ```
109
+
110
+ - `views/partials/canonical-link.pug`
111
+
112
+ ```pug
113
+ if (meta.canonicalLink)
114
+ link(href=meta.canonicalLink.href, rel=meta.canonicalLink.rel)
115
+ ```
116
+
117
+ - `views/partials/alternate-links.pug`
118
+ ```pug
119
+ if (meta.alternateLinks && meta.alternateLinks.length > 0)
120
+ each alternate in meta.alternateLinks
121
+ link(href=alternate.href, hreflang=alternate.hreflang, rel=alternate.rel)
122
+ ```
123
+
124
+ You can copy or customize these templates for full control.
125
+
126
+ ## πŸ§ͺ Development
127
+
128
+ ```bash
129
+ npm install
130
+ npm run test
131
+ ```
132
+
133
+ Includes unit and integration tests using [Vitest](https://vitest.dev) and [Pug](https://pugjs.org).
134
+
135
+ ## πŸ§‘β€πŸ’» Author
136
+
137
+ Michael Becker
138
+ [GitHub](https://github.com/seebaermichi)
139
+
140
+ ## πŸ“¦ License
141
+
142
+ MIT
package/config/canonical-links.yaml ADDED
@@ -0,0 +1,6 @@
1
+ app_origin: https://example.com
2
+ page_identifier: slug
3
+ available_languages:
4
+ - en
5
+ - es
6
+ - fr
package/index.js ADDED
@@ -0,0 +1,62 @@
1
+ import path from 'path'
2
+ import { getConfig } from '@nera-static/plugin-utils'
3
+
4
+ const HOST_CONFIG_PATH = path.resolve(
5
+ process.cwd(),
6
+ 'config/canonical-links.yaml'
7
+ )
8
+
9
+ const config = getConfig(HOST_CONFIG_PATH)
10
+
11
+ function getOrigin(data) {
12
+ return data.app.origin || config.app_origin
13
+ }
14
+
15
+ function getAlternates(pageMeta, data) {
16
+ const pageIdentifier = config.page_identifier || 'slug'
17
+ const availableLanguages = config.available_languages || []
18
+ const multiLangCanonicals = []
19
+
20
+ availableLanguages.forEach((availableLang) => {
21
+ if (pageMeta.lang && availableLang !== pageMeta.lang) {
22
+ const relCanonical = data.pagesData.find(
23
+ ({ meta }) =>
24
+ meta.lang === availableLang &&
25
+ meta[pageIdentifier] === pageMeta[pageIdentifier]
26
+ )
27
+
28
+ if (relCanonical) {
29
+ multiLangCanonicals.push({
30
+ href: `${getOrigin(data)}${relCanonical.meta.href}`,
31
+ hreflang: availableLang,
32
+ rel: 'alternate',
33
+ })
34
+ }
35
+ }
36
+ })
37
+
38
+ return multiLangCanonicals
39
+ }
40
+
41
+ function getCanonical(meta, data) {
42
+ return {
43
+ href: `${getOrigin(data)}${meta.href}`,
44
+ rel: 'canonical',
45
+ }
46
+ }
47
+
48
+ export function getMetaData(data) {
49
+ if (!config) {
50
+ return data.pagesData
51
+ }
52
+
53
+ return data.pagesData.map(({ content, meta }) => {
54
+ return {
55
+ content,
56
+ meta: Object.assign({}, meta, {
57
+ canonicalLink: getCanonical(meta, data),
58
+ alternateLinks: getAlternates(meta, data),
59
+ }),
60
+ }
61
+ })
62
+ }
package/package.json ADDED
@@ -0,0 +1,50 @@
1
+ {
2
+ "name": "@nera-static/plugin-canonical-links",
3
+ "version": "2.0.0",
4
+ "description": "A plugin for Nera static site generator to create canonical links in to be used in the head.",
5
+ "main": "index.js",
6
+ "scripts": {
7
+ "lint": "eslint .",
8
+ "test": "vitest"
9
+ },
10
+ "type": "module",
11
+ "exports": {
12
+ ".": "./index.js"
13
+ },
14
+ "files": [
15
+ "config",
16
+ "index.js",
17
+ "views"
18
+ ],
19
+ "keywords": [
20
+ "nera",
21
+ "plugin",
22
+ "canonical links",
23
+ "static-site",
24
+ "template"
25
+ ],
26
+ "author": "Michael Becker",
27
+ "license": "MIT",
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "https://github.com/seebaermichi/nera-plugin-canonical-links"
31
+ },
32
+ "bugs": {
33
+ "url": "https://github.com/seebaermichi/nera-plugin-canonical-links/issues"
34
+ },
35
+ "homepage": "https://github.com/seebaermichi/nera-plugin-canonical-links#readme",
36
+ "dependencies": {
37
+ "@nera-static/plugin-utils": "^1.0.3"
38
+ },
39
+ "engines": {
40
+ "node": ">=18"
41
+ },
42
+ "devDependencies": {
43
+ "cheerio": "^1.1.0",
44
+ "eslint": "^9.31.0",
45
+ "husky": "^9.1.7",
46
+ "pug": "^3.0.3",
47
+ "vitest": "^3.2.4"
48
+ },
49
+ "sideEffects": false
50
+ }
package/views/index.pug ADDED
@@ -0,0 +1,2 @@
1
+ include partials/canonical-link
2
+ include partials/alternate-links
package/views/partials/alternate-links.pug ADDED
@@ -0,0 +1,3 @@
1
+ if (meta.alternateLinks && meta.alternateLinks.length > 0)
2
+ each alternate in meta.alternateLinks
3
+ link(href=alternate.href, hreflang=alternate.hreflang, rel=alternate.rel)
package/views/partials/canonical-link.pug ADDED
@@ -0,0 +1,2 @@
1
+ if (meta.canonicalLink)
2
+ link(href=meta.canonicalLink.href, rel=meta.canonicalLink.rel)