@nera-static/plugin-canonical-links 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.0] - 2026-07-19
+
+### Fixed
+
+-   no longer emits `<link rel="canonical" href="undefined/...">` on every page
+    when no origin is configured. That markup was worse than none — it told
+    search engines the authoritative URL was a broken string, and nothing was
+    printed to warn about it. The plugin now warns once and leaves pages
+    untouched
+
+### Added
+
+-   `publish-template` command (`npx nera-canonical-links`), so the shipped
+    templates can be copied into `views/vendor/` like every other plugin.
+    Previously there was no publish path at all and the README worked around it
+    by including straight out of `node_modules/`
+-   `--force` to re-publish over existing templates, discarding local edits
+
+### Changed
+
+-   `@nera-static/plugin-utils` range widened to `^1.2.0`, which is what makes
+    `partials/` publish alongside `index.pug`
+-   config is resolved per call rather than at module load
+-   README: `app_origin` was documented as overriding `app.origin`. It is the
+    other way round — `app.origin` wins. The docs now match the code
+-   README: documents that omitting `available_languages` silently disables
+    alternate links
+
+### Removed
+
+-   dead `if (!config)` guard — `getConfig` returns `{}`, so it never fired
+
+## [2.0.1] - 2025-07-19
+
+### Added
+
+-   Complete CHANGELOG.md with full version history
+-   Enhanced package.json keywords for better discoverability
+-   Compatibility section in README.md
+
+### Changed
+
+-   Improved documentation with Nera v4.1.0+ compatibility notes
+-   Enhanced keywords for NPM search optimization
+-   Better structured development and deployment information
+
+### Fixed
+
+-   Documentation consistency and clarity improvements
+
+## [2.0.0] - 2025-07-19
+
+### Breaking Changes
+
+-   Updated for compatibility with Nera v4.1.0+
+-   Requires Node.js >= 18
+
+### Added
+
+-   Support for Nera's enhanced plugin architecture
+-   Improved error handling and logging compatibility
+-   Full compatibility with Nera's parallel plugin loading
+
+### Changed
+
+-   Updated dependencies to latest versions
+-   Enhanced test coverage and reliability
+-   Improved documentation and development setup
+
+### Technical
+
+-   Compatible with Nera's new plugin data merging system
+-   Optimized for parallel execution performance
+-   Enhanced development tooling with Husky and ESLint
+
+## [1.x] - Previous Versions
+
+### Features
+
+-   Canonical link generation for SEO optimization
+-   Multi-language alternate link support
+-   Configurable page identifier and language detection
+-   Pug template integration for head section
+
+### Configuration
+
+-   Flexible origin URL configuration
+-   Support for multiple available languages
+-   Customizable page identifier field
+-   YAML-based configuration system
+
+[2.0.1]: https://github.com/seebaermichi/nera-plugin-canonical-links/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/seebaermichi/nera-plugin-canonical-links/compare/v1.0.0...v2.0.0

package/README.md

@@ -39,17 +39,42 @@ available_languages:
     - fr
 ```
 
--   `app_origin`: The canonical base URL (overrides `app.origin`).
+-   `app_origin`: The canonical base URL. Used as a fallback — if `origin` is
+    set in `config/app.yaml`, **that wins**.
 -   `page_identifier`: Shared key to match localized versions (defaults to `slug`).
--   `available_languages`: List of supported language codes (used to create alternate links).
+-   `available_languages`: List of supported language codes, used to create
+    alternate links. **Omitting it disables alternate links entirely** — you
+    get canonical tags only, with no warning.
+
+If neither `app.origin` nor `app_origin` resolves, the plugin generates no
+canonical links at all and prints a warning. Earlier versions emitted
+`<link rel="canonical" href="undefined/…">` in that case.
+
+## 🛠️ Template Publishing
+
+Copy the plugin's templates into your project:
+
+```bash
+npx nera-canonical-links
+```
+
+This copies `index.pug` and its `partials/` to:
+
+```
+views/vendor/plugin-canonical-links/
+```
+
+Publishing **skips** if that directory already exists, so your edits are never
+overwritten. To pull in updated templates after an upgrade, discarding your
+changes to them, use `npx nera-canonical-links --force`.
 
 ## 📄 Usage in Templates
 
-Include the plugin’s view in your layout head:
+Include the published view in your layout head:
 
 ```pug
 head
-    include /node_modules/@nera-static/plugin-canonical-links/views/index
+    include vendor/plugin-canonical-links/index
 ```
 
 This will generate:
@@ -121,7 +146,7 @@ The plugin provides a view file that includes two partials:
             link(href=alternate.href, hreflang=alternate.hreflang, rel=alternate.rel)
     ```
 
-You can copy or customize these templates for full control.
+Publish them (see above) and customize the copies for full control.
 
 ## 🧪 Development
 

package/bin/publish-template.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { publishAllTemplates } from '@nera-static/plugin-utils'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const pluginName = 'plugin-canonical-links'
+const sourceDir = path.resolve(__dirname, '../views/')
+const force = process.argv.includes('--force')
+
+const result = publishAllTemplates({
+    pluginName,
+    sourceDir,
+    force,
+})
+
+process.exit(result ? 0 : 1)

package/index.js

@@ -1,18 +1,22 @@
 import path from 'path'
 import { getConfig } from '@nera-static/plugin-utils'
 
-const HOST_CONFIG_PATH = path.resolve(
-    process.cwd(),
-    'config/canonical-links.yaml'
-)
-
-const config = getConfig(HOST_CONFIG_PATH)
+// Resolved per call rather than at module scope: the host project's cwd is
+// what matters, and resolving lazily is what makes this testable.
+function getHostConfig() {
+    return getConfig(path.resolve(process.cwd(), 'config/canonical-links.yaml'))
+}
 
-function getOrigin(data) {
-    return data.app.origin || config.app_origin
+/**
+ * The canonical base URL. `app.origin` from config/app.yaml wins over the
+ * plugin's own `app_origin` — the opposite of what the README claimed
+ * before 2.1.0.
+ */
+function getOrigin(data, config) {
+    return data.app?.origin || config.app_origin
 }
 
-function getAlternates(pageMeta, data) {
+function getAlternates(pageMeta, data, config, origin) {
     const pageIdentifier = config.page_identifier || 'slug'
     const availableLanguages = config.available_languages || []
     const multiLangCanonicals = []
@@ -27,7 +31,7 @@ function getAlternates(pageMeta, data) {
 
             if (relCanonical) {
                 multiLangCanonicals.push({
-                    href: `${getOrigin(data)}${relCanonical.meta.href}`,
+                    href: `${origin}${relCanonical.meta.href}`,
                     hreflang: availableLang,
                     rel: 'alternate',
                 })
@@ -38,15 +42,26 @@ function getAlternates(pageMeta, data) {
     return multiLangCanonicals
 }
 
-function getCanonical(meta, data) {
+function getCanonical(meta, origin) {
     return {
-        href: `${getOrigin(data)}${meta.href}`,
+        href: `${origin}${meta.href}`,
         rel: 'canonical',
     }
 }
 
 export function getMetaData(data) {
-    if (!config) {
+    const config = getHostConfig()
+    const origin = getOrigin(data, config)
+
+    // Without an origin every page used to get
+    // <link rel="canonical" href="undefined/blog/post.html">, which is worse
+    // than emitting nothing at all — it hands search engines a broken URL as
+    // the authoritative one. Bail out loudly instead.
+    if (!origin) {
+        console.warn(
+            '⚠️ plugin-canonical-links: no origin configured, so no canonical links were generated.\n' +
+                '    Set `origin` in config/app.yaml, or `app_origin` in config/canonical-links.yaml.'
+        )
         return data.pagesData
     }
 
@@ -54,8 +69,8 @@ export function getMetaData(data) {
         return {
             content,
             meta: Object.assign({}, meta, {
-                canonicalLink: getCanonical(meta, data),
-                alternateLinks: getAlternates(meta, data),
+                canonicalLink: getCanonical(meta, origin),
+                alternateLinks: getAlternates(meta, data, config, origin),
             }),
         }
     })

package/package.json

@@ -1,9 +1,10 @@
 {
     "name": "@nera-static/plugin-canonical-links",
-    "version": "2.0.1",
+    "version": "2.1.0",
     "description": "A plugin for Nera static site generator to create canonical links in to be used in the head.",
     "main": "index.js",
     "scripts": {
+        "publish-template": "node ./bin/publish-template.js",
         "lint": "eslint .",
         "test": "vitest"
     },
@@ -11,10 +12,15 @@
     "exports": {
         ".": "./index.js"
     },
+    "bin": {
+        "nera-canonical-links": "./bin/publish-template.js"
+    },
     "files": [
+        "bin",
         "config",
         "index.js",
-        "views"
+        "views",
+        "CHANGELOG.md"
     ],
     "keywords": [
         "nera",
@@ -38,7 +44,7 @@
     },
     "homepage": "https://github.com/seebaermichi/nera-plugin-canonical-links#readme",
     "dependencies": {
-        "@nera-static/plugin-utils": "^1.0.3"
+        "@nera-static/plugin-utils": "^1.2.0"
     },
     "engines": {
         "node": ">=18"