@jungvonmatt/cssg-plugin-hugo 1.0.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.0](https://github.com/jungvonmatt/contentful-ssg/compare/v0.17.3...v1.0.0-alpha.0) (2021-11-25)
+
+**Note:** Version bump only for package @jungvonmatt/cssg-plugin-hugo

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Jung von Matt TECH (https://www.jvm.com/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# cssg-plugin-hugo
+
+Provides support for the [hugo](https://gohugo.io/) static site generator.
+
+This plugin provides some usefull but opinionated settings/features for the use with the hugo static site generator.
+
+**Multilingual Mode**
+
+This plugin automatically generates a `/config/_default/languages.toml` file for you based on your locale configuration in contentful.
+Your content is organized using different content directories for each of the languages. See https://gohugo.io/content-management/multilingual/#translation-by-content-directory
+
+**Translation of Strings**
+
+When you provide a content type for string translations, the content is automatically collected and stored as translations present in i18n/ at the root of your project.
+See https://gohugo.io/content-management/multilingual/#translation-of-strings.
+
+The configured translations can then be used using the [`i18n`](https://gohugo.io/functions/i18n/) function.
+
+```go
+{{ i18n "translation_id" }}
+```
+
+<details>
+    <summary>Contentful migration for `d-i18n`</summary>
+    <p>
+
+```js
+
+module.exports = function (migration) {
+  const dI18n = migration
+    .createContentType('d-i18n')
+    .name('Data: i18n')
+    .description('Key value store for i18n')
+    .displayField('key');
+
+  dI18n
+    .createField('key')
+    .name('Key')
+    .type('Symbol')
+    .localized(false)
+    .required(true)
+    .validations([
+      {
+        unique: true,
+      },
+    ])
+    .disabled(false)
+    .omitted(false);
+
+  dI18n
+    .createField('other')
+    .name('Value')
+    .type('Symbol')
+    .localized(true)
+    .required(true)
+    .validations([])
+    .disabled(false)
+    .omitted(false);
+
+  dI18n
+    .createField('one')
+    .name('Singular value')
+    .type('Symbol')
+    .localized(true)
+    .required(false)
+    .validations([])
+    .disabled(false)
+    .omitted(false);
+
+  dI18n.changeFieldControl('key', 'builtin', 'singleLine', {});
+  dI18n.changeFieldControl('other', 'builtin', 'singleLine', {});
+  dI18n.changeFieldControl('one', 'builtin', 'singleLine', {
+    helpText: 'Optionally pass a dedicated singular value',
+  });
+};
+```
+</p>
+</details>
+
+**Content Organization**
+
+Your content will be organised according to hugo's best practices inside the `content` directory at the root of your project. See https://gohugo.io/content-management/organization/
+In order for this to work properly it is required to provide a `slug` field in your content tyopes describing pages as well as a reference to the parent entry.
+It's also required to have a settings content type in contentful which holds a reference to the home page.
+This way we can compute the folder structure inside `/content` to utilize the full potential of hugos [content sections](https://gohugo.io/content-management/sections/).
+
+**Naming Convention**
+All keys in frontmatter besides internal ones like `translationKey` are automatically converted to `snake_case` to prevent issues with hugo storing all `.Params` as lowercase.
+
+> Page-level .Params are only accessible in lowercase.
+
+See https://gohugo.io/variables/page/#page-level-params and https://discourse.gohugo.io/t/config-params-should-be-all-lowercase-or-not/5051
+
+**Contentful References**
+
+All reference fields are extended by the path to the associated markdown file so you can easily load the content:
+
+```go
+{{ with .Params.reference_field }}
+  {{ $page := .Site.GetPage(.path) }}
+{{ end }}
+```
+
+
+## Install
+
+`npm install @jungvonmatt/cssg-plugin-hugo`
+
+## How to use
+
+```js
+// In your contentful-ssg.config.js
+plugins: [
+  {
+    resolve: `@jungvonmatt/cssg-plugin-hugo`,
+    options: {
+      // Add any options here
+    },
+  },
+];
+```
+
+## Options
+
+| Name           | Type      | Default                           | Description                                                                                                                                                                                                                                                                                                                                     |
+| -------------- | --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| typeIdSettings | `string`  | `'d-settings'`                    | The id of the settings content type.                                                                                                                                                                                                                                                                                                            |
+| typeIdI18n     | `string`  | `'d-i18n'`                        | The id of the i18n content type for the translation of strings.                                                                                                                                                                                                                                                                                                                |
+| fieldIdHome    | `string`  | `'home'`                          | The id of reference field to the home page in the settings content type.                                                                                                                                                                                                                                                                        |
+| fieldIdSlug    | `string`  | `'slug'`                          | The id of the slug field in page content types.                                                                                                                                                                                                                                                                                                 |
+| fieldIdParent  | `string`  | `'parent_page'`                   | The id of the parent page reference field in page content types.                                                                                                                                                                                                                                                                                |
+| languageConfig | `boolean` | `true`                            | Auto-generate the hugo language config based on your locale configuration in contentful.                                                                                                                                                                                                                                                        |
+| typeConfig     | `object`  | `{ page: ['page'], data: ['d-*']}` | Pass a map with entry types (`data`, `map`) pointing to one or more glob patterns matching the content type ids.\ Data types will be stored inside the `/data/` directory. \ pages types will be stored inside `/content/<locale>/`.\ All content types that do not match are considered headless and will be stored inside `/content/headless` |
+
+Example:
+
+```js
+// In your contentful-ssg.config.js
+plugins: [
+  {
+    resolve: `@jungvonmatt/cssg-plugin-hugo`,
+    options: {
+      typeIdSettings: 'd-settings',
+      typeIdI18n: 'd-i18n',
+      languageConfig: true,
+      fieldIdHome: 'home',
+      fieldIdSlug: 'slug',
+      fieldIdParent: 'parent_page',
+      typeConfig: {
+        page: ['page'],
+        data: ['d-*'],
+      },
+    },
+  },
+];
+```

package/index.js

@@ -0,0 +1,243 @@
+
+import mergeOptionsModule from 'merge-options';
+
+import {snakeCaseKeys} from '@jungvonmatt/contentful-ssg/lib/object';
+import mm from 'micromatch';
+import {existsSync} from 'fs';
+import {writeFile, readFile} from 'fs/promises';
+import path from 'path';
+
+const mergeOptions = mergeOptionsModule.bind({ ignoreUndefined: true });
+
+export const TYPE_PAGE = 'page';
+export const TYPE_DATA = 'data';
+export const TYPE_HEADLESS = 'headless';
+
+const defaultOptions = {
+  typeIdSettings: 'd-settings',
+  typeIdI18n: 'd-i18n',
+  languageConfig: true,
+  fieldIdHome: 'home',
+  fieldIdSlug: 'slug',
+  fieldIdParent: 'parent_page',
+  typeConfig:  {
+    [TYPE_PAGE]: ['page'],
+    [TYPE_DATA]: ['d-*'],
+  },
+}
+
+export default (args) => {
+  const options = {...defaultOptions, ...(args || {})}
+
+
+
+  const getSettingsHelper = (runtimeContext) => {
+    let settings = {};
+    if (options.typeIdSettings) {
+      settings = Object.fromEntries(Array.from((runtimeContext?.localized ?? new Map()).entries()).map(([locale, contentfulData]) => {
+        const entryMap = contentfulData?.entryMap ?? new Map();
+        const settingsEntries = (Array.from(entryMap.values())).filter(entry => (entry?.sys?.contentType?.sys?.id ?? 'unknown') === options.typeIdSettings);
+        const settingsFields = settingsEntries.map(entry => entry?.fields ?? {});
+        return [locale, mergeOptions(...settingsFields)];
+      }));
+    }
+
+    return  (key, locale, defaultValue) => settings?.[locale]?.[key] ?? defaultValue;
+  }
+
+  const getEntryType = (transformContext) => {
+    const {contentTypeId} = transformContext;
+    const [type = TYPE_HEADLESS] = Object.entries(options?.typeConfig ?? {}).find(([,pattern]) => mm.isMatch(contentTypeId, pattern)) || [];
+
+    return type;
+  }
+
+
+
+  return {
+    // Before hook
+    async before(runtimeContext) {
+      const {helper,converter, data, localized} = runtimeContext;
+      const locales = data?.locales ?? [];
+
+      // initialize getSettings
+      const getSettings = getSettingsHelper(runtimeContext);
+      helper.getSettings = getSettings;
+      // Write config toml according to locale settings in contentful
+      if (options.languageConfig) {
+        const rootDir = runtimeContext?.config?.rootDir ?? process.cwd();
+        const dst = path.join(rootDir, 'config/_default/languages.toml');
+        const languageConfig = Object.fromEntries(
+          locales.map((locale) => {
+            const { code, name: languageName } = locale;
+            // Currently Hugo language internals lowercase language codes,
+            // which can cause conflicts with settings like defaultContentLanguage
+            // which are not lowercased
+            // https://github.com/gohugoio/hugo/issues/7344
+            const languageCode = code.toLowerCase();
+            const [languageNameShort] = languageCode.split('-');
+            return [
+              code,
+              {
+                contentDir: `content/${languageCode}`,
+                languageCode,
+                languageName,
+                languageNameShort,
+                weight: locale.default ? 1 : 2,
+              },
+            ];
+          })
+        );
+        await writeFile(
+          dst,
+          converter.toml.stringify(languageConfig)
+        );
+      }
+
+      // Find section pages and add them to the runtimeconfig
+      const enhancedLocalized = new Map(Array.from(localized.entries()).map(([localeCode, contentfulData]) => {
+        const {entries} = contentfulData;
+        const sectionIds = entries.reduce((nodes, entry) => {
+          const id = entry?.fields?.[options.fieldIdParent]?.sys?.id;
+          if (id) {
+            nodes.add(id);
+          }
+
+          return nodes;
+        }, new Set());
+        return [localeCode, {...contentfulData, sectionIds}];
+      }));
+
+      return {...runtimeContext, helper, localized: enhancedLocalized};
+    },
+
+    /**
+     * Add path markdown files for entry links
+     * @param transformContext
+     * @param runtimeContext
+     * @returns
+     */
+    async mapEntryLink(
+      transformContext,
+      runtimeContext,
+      prev
+    ) {
+      const directory = await runtimeContext.hooks.mapDirectory(transformContext);
+      const filename = await runtimeContext.hooks.mapFilename(transformContext);
+
+      return {...prev, path: path.join(directory,filename)};
+    },
+
+    /**
+     * Map directories
+     * @param transformContext
+     * @returns
+     */
+    async mapDirectory(transformContext) {
+      const {contentTypeId, locale} = transformContext;
+      const type = getEntryType(transformContext);
+
+      if (type === TYPE_DATA) {
+        return '../data';
+      }
+
+      if (contentTypeId === TYPE_PAGE) {
+        return locale.code;
+      }
+
+      return path.join('headless', contentTypeId);
+    },
+
+    /**
+     * Map filenames data files to data, headless bundles to headless folder and pages in a
+     * directory structure which matches the sitemap
+     * @param transformContext
+     * @param runtimeContext
+     * @returns
+     */
+    async mapFilename(transformContext, runtimeContext) {
+      const {id, locale,  entry, contentTypeId, utils} = transformContext;
+      const {helper, localized} = runtimeContext;
+      const sectionIds = localized?.get(locale.code)?.sectionIds ?? new Set();
+
+      const type = getEntryType(transformContext);
+
+      const home = helper.getSettings(options.fieldIdHome, locale.code);
+      const homeId = home?.sys?.id;
+
+     if (homeId && entry?.sys?.id === homeId) {
+        return `/_index.md`;
+     }
+
+      if (contentTypeId === options.typeIdSettings) {
+        return path.join(locale.code, `settings.json`);
+      }
+
+      if (type === TYPE_DATA) {
+        return path.join(locale.code, contentTypeId, `${id}.json`);
+      }
+
+      if (type === TYPE_PAGE && sectionIds.has(id)) {
+        const slugs = utils.collectValues(`fields.${options.fieldIdSlug}`, {
+          linkField: `fields.${options.fieldIdParent}`,
+          entry,
+        });
+        return path.join(...(slugs || []), `_index.md`)
+      }
+
+      if (type === TYPE_PAGE) {
+        const slugs = utils.collectParentValues(`fields.${options.fieldIdSlug}`, {
+          linkField: `fields.${options.fieldIdParent}`,
+          entry
+        });
+
+        return path.join(...(slugs || []), `${entry?.fields?.[options.fieldIdSlug] ?? 'unknown'}.md`)
+      }
+
+      return path.join(id, `index.${locale.code}.md`);
+    },
+
+    async transform(transformContext, runtimeContext) {
+      const {content, id, contentTypeId, locale} = transformContext;
+      const contentDir = runtimeContext.config.directory;
+      const toml = runtimeContext.converter.toml;
+      const type = getEntryType(transformContext);
+
+      // Automatically store dictionary entries in i18n/[locale].json
+      // See https://gohugo.io/content-management/multilingual/#query-basic-translation
+      if (options.typeIdI18n && contentTypeId === options.typeIdI18n) {
+        const { key, other, one } = content;
+        const translations = one ? { one, other } : { other };
+
+        const dictionaryPath = path.join(contentDir, `../i18n/${locale.code}.toml`);
+        const oldContent = existsSync(dictionaryPath) ? toml.parse(await readFile(dictionaryPath, 'utf8')) : {};
+        await writeFile(
+          dictionaryPath,
+          toml.stringify({ ...oldContent, [key]: translations }, undefined, '  ')
+        );
+
+        // dont't write i-18n objects to the content folder
+        return undefined;
+      }
+
+      if (type === TYPE_PAGE) {
+        return {...snakeCaseKeys({
+          ...content,
+
+        }), translationKey: id};
+      }
+
+      if (type === TYPE_HEADLESS) {
+        return snakeCaseKeys({
+          ...content,
+          headless: true,
+        });
+      }
+
+      return snakeCaseKeys(content);
+    }
+  };
+};
+
+
+

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@jungvonmatt/cssg-plugin-hugo",
+  "version": "1.0.0-alpha.0",
+  "description": "",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jungvonmatt/contentful-ssg.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "Ben Zörb",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/jungvonmatt/contentful-ssg/issues"
+  },
+  "homepage": "https://github.com/jungvonmatt/contentful-ssg#readme",
+  "dependencies": {
+    "@jungvonmatt/contentful-ssg": "^1.0.0-alpha.0",
+    "merge-options": "^3.0.4",
+    "micromatch": "^4.0.4"
+  },
+  "gitHead": "3fdc0fb66ce8285206bd116a8d66e7a6a9990f84"
+}