@hestia-earth/guide 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+### 0.0.1 (2024-10-29)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2024 Harmonised Environmental Storage and Tracking of the Impacts of Agriculture (HESTIA) Project
+
+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,81 @@
+# Hestia Guide
+
+This repository contains the raw content of the guide written in Markdown language.
+
+Every file under _src/content_ will be automatically deployed to https://hestia-earth.gitlab.io/hestia-guide domain for testing.
+
+Example:
+- src/content/introduction.md will be deployed to https://hestia-earth.gitlab.io/hestia-guide/introduction
+- src/content/how-to-upload.md will be deployed to https://hestia-earth.gitlab.io/hestia-guide/how-to-upload
+
+Note: only lower chars, dashes (`-`) and numbers are allowed in the filenames.
+
+## Writing Guidelines
+
+1. Create a new file under `src/content` and make sure the filename only uses lowercase letters, numbers and dashes.
+1. Start the file with a header level 1 using a single `#`. Example:
+
+```markdown
+# This is the header
+
+This is the content.
+
+## This is a sub-header
+```
+
+The header level 1 will be automatically used as Title for the Guide page, so please try to keep it short.
+
+The second line (omitting the blank lines) will be used as abstract.
+
+**Important**: the folder and the file name should reflect the Guide navigation structure.
+
+Example: if you are adding a page called "Signing in" under "HESTIA 101", please add `src/content/hestia-101/3_signin.md` file. This will automatically:
+- show the page under "HESTIA 101" menu
+- show the page as item number 3 in the menu (if there are 2 pages before number `1_`, `2_` in the same folder)
+- match the page with the url `hestia-101-signin`
+- the title of the page will be used also in the menu
+
+### Adding metadata
+
+It is possible to add a list of metadata, using the following format:
+```
+/<name of metadata> ~Title~
+```
+
+These metadata must be added at the end of the file, one per line. The list of metadata is:
+
+| Name | Can be added multiple times | Description |
+| ---- | ---- | ---- |
+| `previous` | ❌ | Link to the previous guide page (will show at the bottom) |
+| `next` | ❌ | Link to the next guide page (will show at the bottom) |
+| `tag` | ✅ | Used to group pages together as "related" |
+
+**Example:**
+
+```markdown
+# This is the title
+
+This is the content of the page.
+
+/tag ~Hestia~
+/tag ~Beginners~
+/previous ~how-to-upload~
+/next ~how-to-access-data~
+```
+
+### Adding images or videos
+
+To add an image or a video to a page:
+- add the file under the `src/assets` folder. Note: you can use sub-directories to organise the files.
+- make sure to use a simple name, without special characters. So only letters and numbers, dashes or underscores.
+- in the content of the page, use either
+  ```html
+  <img src="/guide-content/assets/<path to the file>" alt="Text to describe the image" height="auto">
+  ```
+  or to use videos in different formats
+  ```html
+  <video width="320" height="240" controls>
+    <source src="/guide-content/assets/<path to the file>.mp4" type="video/mp4">
+    <source src="/guide-content/assets/<path to the file>.ogg" type="video/ogg">
+  </video>
+  ```

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export interface IGuideIndexPageContent {
+    id: string;
+    mdPath: string;
+    jsonPath: string;
+    title: string;
+    createdAt: string;
+    updatedAt?: string;
+    tags?: Record<string, string[]>;
+}
+type guidePages = {
+    [url: string]: IGuideIndexPage;
+};
+export interface IGuideIndexPage {
+    content?: IGuideIndexPageContent;
+    pages?: guidePages;
+}
+export declare const loadIndex: () => IGuideIndexPage;
+export declare const findPage: (id: string) => IGuideIndexPageContent;
+export interface IGuidePageContent {
+    content: string;
+    tags?: Record<string, string[]>;
+}
+export declare const loadPage: ({ jsonPath }: IGuideIndexPageContent) => IGuidePageContent;
+export {};

package/dist/index.js

@@ -0,0 +1,48 @@
+"use strict";
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPage = exports.findPage = exports.loadIndex = void 0;
+var contentDir = "../content";
+var loadIndex = function () {
+    return require("".concat(contentDir, "/index.json"));
+};
+exports.loadIndex = loadIndex;
+var flatPages = function (_a) {
+    var content = _a.content, pages = _a.pages;
+    return __spreadArray([
+        content
+    ], __read(Object.values(pages || {}).flatMap(function (values) { return flatPages(values); })), false).filter(Boolean);
+};
+var findPage = function (id) {
+    return flatPages((0, exports.loadIndex)()).find(function (page) { return page.id === id; });
+};
+exports.findPage = findPage;
+var loadPage = function (_a) {
+    var jsonPath = _a.jsonPath;
+    return require("".concat(contentDir, "/").concat(jsonPath));
+};
+exports.loadPage = loadPage;

package/envs/.dev.env

@@ -0,0 +1,2 @@
+export BUCKET='hestia-dev-guide'
+export DISTRIB_ID='E3393LZT5IR3TE'

package/envs/.develop.env

@@ -0,0 +1,2 @@
+export BUCKET='hestia-staging-guide'
+export DISTRIB_ID='ELURHKMA1X6F1'

package/envs/.master.env

@@ -0,0 +1,2 @@
+export BUCKET='hestia-prod-guide'
+export DISTRIB_ID='E3HOSZSTUYX9WN'

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hestia-earth/guide",
+  "version": "0.0.1",
+  "description": "Hestia Guide pages",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "test": "node scripts/check-content.js",
+    "build": "rm -rf dist && tsc -p tsconfig.dist.json",
+    "build:www": "node scripts/build.js",
+    "build:content": "rimraf content && node scripts/build-content.js && node scripts/build-index.js",
+    "release": "standard-version -a",
+    "postrelease": "git push origin master --follow-tags"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/hestia-earth/hestia-guide.git"
+  },
+  "keywords": [
+    "hestia",
+    "guide",
+    "markdown"
+  ],
+  "author": "Guillaume Royer <guillaume@hestia.earth>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://gitlab.com/hestia-earth/hestia-guide/issues"
+  },
+  "homepage": "https://gitlab.com/hestia-earth/hestia-guide#readme",
+  "devDependencies": {
+    "@commitlint/cli": "^19.5.0",
+    "@commitlint/config-conventional": "^19.5.0",
+    "git-date-extractor": "^4.0.1",
+    "husky": "^4.3.8",
+    "rimraf": "^6.0.1",
+    "standard-version": "^9.5.0"
+  },
+  "dependencies": {
+    "typescript": "^5.6.3"
+  }
+}

package/scripts/build-content.js

@@ -0,0 +1,54 @@
+const { writeFileSync } = require("fs");
+const { join } = require("path");
+
+const {
+  mkdirs,
+  encoding,
+  srcDir,
+  listContent,
+  readContent,
+  removeContentTags,
+  getTags,
+} = require("./utils");
+
+const outputDir = join(__dirname, "..", "content");
+
+mkdirs(outputDir);
+
+const destFilename = (filename) =>
+  `${outputDir}/${filename.replace(srcDir, "").replace(/[\d]+_/g, "")}`;
+
+const buildMarkdownContent = (filename) => {
+  const content = readContent(filename, true);
+  const dest = destFilename(filename);
+  mkdirs(dest);
+  writeFileSync(dest, content, encoding);
+  return filename;
+};
+
+const buildJSONContent = (filename) => {
+  const content = readContent(filename, false);
+  const tags = getTags(content);
+  const dest = destFilename(filename).replace(".md", ".json");
+  mkdirs(dest);
+  writeFileSync(
+    dest,
+    JSON.stringify(
+      {
+        tags,
+        content: removeContentTags(content),
+      },
+      null,
+      2
+    ),
+    encoding
+  );
+  return filename;
+};
+
+const build = () => {
+  const files = listContent();
+  return files.map(buildMarkdownContent).map(buildJSONContent);
+};
+
+build();

package/scripts/build-index.js

@@ -0,0 +1,91 @@
+const { writeFileSync, readdirSync } = require("fs");
+const { join } = require("path");
+const { getStamps } = require("git-date-extractor");
+
+const {
+  encoding,
+  ROOT,
+  srcDir,
+  mkdirs,
+  contentDir,
+  isDir,
+  listContent,
+  readContent,
+  contentUrl,
+  getTitle,
+  getTags,
+} = require("./utils");
+
+const outputDir = join(__dirname, "..", "content");
+
+mkdirs(outputDir);
+
+const fileData = (stamps, filename) => {
+  const { created, modified } = stamps[join(contentDir, filename)];
+  const content = readContent(filename);
+  const lines = content.split("\n").filter(Boolean);
+  const title = getTitle(lines[0]);
+  const tags = getTags(content);
+  const filepath = filename.replace(/^[/]/g, "").replace(/[\d]+_/g, "");
+  const id = filepath
+    .replace(".md", "")
+    .replace(/\//g, "-")
+    .replace("-content", "");
+  return {
+    id,
+    mdPath: filepath,
+    jsonPath: filepath.replace(".md", ".json"),
+    title,
+    createdAt: new Date(created * 1000).toJSON(),
+    updatedAt: new Date(modified * 1000).toJSON(),
+    tags,
+  };
+};
+
+const folderData = (stamps, folder) => {
+  const pages = listContent(join(srcDir, folder)).filter(
+    (f) => !f.endsWith("0_content.md")
+  );
+  return {
+    content: fileData(stamps, join(folder, "0_content.md")),
+    ...(pages.length
+      ? {
+          pages: Object.fromEntries(
+            pages
+              .map((f) => f.replace(srcDir, ""))
+              .map((filename) => [
+                contentUrl(filename),
+                { content: fileData(stamps, filename) },
+              ])
+          ),
+        }
+      : {}),
+  };
+};
+
+const run = async () => {
+  const stamps = await getStamps({
+    projectRootPath: ROOT,
+  });
+
+  // keep the folder structure
+  const folders = readdirSync(srcDir).filter((f) => isDir(join(srcDir, f)));
+  const data = folders.map((folder) => [folder, folderData(stamps, folder)]);
+  const pages = Object.fromEntries(data);
+  const content = {
+    pages,
+  };
+
+  writeFileSync(
+    join(outputDir, "index.json"),
+    JSON.stringify(content, null, 2),
+    encoding
+  );
+};
+
+run()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

package/scripts/build.js

@@ -0,0 +1,57 @@
+const { existsSync, copyFileSync, unlinkSync, writeFileSync } = require("fs");
+const { join } = require("path");
+
+const {
+  mkdirs,
+  encoding,
+  srcDir,
+  listContent,
+  readContent,
+} = require("./utils");
+
+const outputDir = join(__dirname, "..", "www");
+
+mkdirs(outputDir);
+
+const copyFile = (src, dest) => {
+  existsSync(dest) && unlinkSync(dest);
+  mkdirs(dest);
+  copyFileSync(src, dest);
+};
+
+const copyTemplates = (folder) => {
+  mkdirs(folder);
+  ["template.css", "template.html", "template.js"].map((v) =>
+    copyFile(join(__dirname, v), join(folder, v.replace("template", "index")))
+  );
+};
+
+const buildContent = (filename) => {
+  const destFolder = join(outputDir, filename.replace(".md", ""));
+  copyTemplates(destFolder);
+
+  const content = readContent(filename, true);
+
+  writeFileSync(join(destFolder, "content.md"), content, encoding);
+};
+
+const generateIndex = (files) => {
+  copyTemplates(outputDir);
+  const content = `
+# Table of Contents
+
+${files
+  .map((f) => f.replace(".md", ""))
+  .map((f) => `- [${f}](./${f})`)
+  .join("\n\n")}
+  `.trim();
+  writeFileSync(join(outputDir, "content.md"), content, encoding);
+};
+
+const build = () => {
+  const files = listContent().map((f) => f.replace(srcDir, ""));
+  generateIndex(files);
+  return files.map(buildContent);
+};
+
+build();

package/scripts/check-content.js

@@ -0,0 +1,80 @@
+const {
+  listContent,
+  readContent,
+  isTag,
+  listAssets,
+  baseAssetRef,
+} = require("./utils");
+
+const allAssets = listAssets();
+
+const checkFilename = (filename) =>
+  filename
+    .split("/")
+    .pop()
+    .replace(".md", "")
+    .match(/^[\d]_[a-z\d\-]+$/g);
+
+const isValidLinks = (url) => !url.match(/\s/g) && !!new URL(url)?.host;
+
+const getUrls = (content) =>
+  (content.match(/href="([^"]*)/g) || []).map((v) => v.replace('href="', ""));
+
+const checkAssets = (content) => {
+  const urls = (content.match(/src="([^"]*)/g) || []).map((v) =>
+    v.replace(`src="${baseAssetRef}`, "")
+  );
+  const invalid = urls.filter((v) => !allAssets.includes(v));
+  if (invalid.length > 0) {
+    console.error(
+      "Invalid referenced assets",
+      invalid.map((v) => `${baseAssetRef}${v}`)
+    );
+  }
+  return invalid.length === 0;
+};
+
+const checks = {
+  'File should start with "# "': (content) => content.startsWith("# "),
+  "Links must be valid": (content) => getUrls(content).every(isValidLinks),
+  "Links must not point to staging website": (content) =>
+    [
+      "http://www-staging.hestia.earth",
+      "https://www-staging.hestia.earth",
+    ].every((v) => !content.includes(v)),
+  'Images and videos must be included in the "src/assets" folder': checkAssets,
+};
+
+const checkContent = (filename) => {
+  const content = readContent(filename);
+  return [
+    checkFilename(filename)
+      ? ""
+      : "File names must contain lowercase letters, numbers or dashes only, and start with a number followed by an underscore for sorting.",
+    ...Object.entries(checks)
+      .filter(([key, value]) => !value(content))
+      .map(([key, value]) => key),
+  ].filter(Boolean);
+};
+
+const run = () => {
+  const files = listContent();
+  const allErrors = files
+    .map((f) => ({
+      f,
+      errors: checkContent(f),
+    }))
+    .filter(({ errors }) => errors.length);
+
+  if (allErrors.length) {
+    allErrors.map(({ f, errors }) => {
+      console.error("Error in", f, ":");
+      errors.map((e) => console.error(`\t- ${e}`));
+    });
+    process.exit(1);
+  } else {
+    process.exit(0);
+  }
+};
+
+run();

package/scripts/template.css

@@ -0,0 +1,6 @@
+#main {
+  height: 100%;
+  width: 100%;
+  padding: 20px;
+  overflow: hidden;
+}

package/scripts/template.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Markdown Preview</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+
+  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/marked/4.2.1/marked.min.js"></script>
+
+  <link rel="stylesheet" href="https://cdn.hestia.earth/prod/styles.css">
+  <link rel="stylesheet" href="index.css">
+</head>
+<body>
+  <noscript>Please enable JavaScript to continue using this application.</noscript>
+
+  <a href="../"><< Back to index</a>
+
+  <div id="main"></div>
+
+  <script type="text/javascript" src="index.js"></script>
+</body>
+</html>

package/scripts/template.js

@@ -0,0 +1,5 @@
+fetch('content.md')
+  .then((response) => response.text())
+  .then((text) => {
+    document.getElementById('main').innerHTML = marked.parse(text);
+  });

package/scripts/utils.js

@@ -0,0 +1,117 @@
+const {
+  readdirSync,
+  readFileSync,
+  lstatSync,
+  existsSync,
+  mkdirSync,
+} = require("fs");
+const { join, resolve, parse } = require("path");
+
+const encoding = "utf8";
+const ROOT = resolve(join(__dirname, ".."));
+const contentDir = join("src", "content");
+const srcDir = join(ROOT, contentDir);
+const assetDir = join(ROOT, "src", "assets");
+
+const isDir = (path) => {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch (_err) {
+    return false;
+  }
+};
+
+const mkdirs = (folder) =>
+  !existsSync(parse(folder).dir) &&
+  mkdirSync(parse(folder).dir, { recursive: true });
+
+const unique = (values) =>
+  values.some((v) => typeof v === "object")
+    ? [...new Set(values.map((v) => JSON.stringify(v)))].map((v) =>
+        JSON.parse(v)
+      )
+    : [...new Set(values)];
+
+const baseAssetRef = "/guide-content/assets";
+const listAssets = (directory = assetDir) =>
+  readdirSync(directory)
+    .flatMap((path) =>
+      isDir(join(directory, path))
+        ? listAssets(join(directory, path))
+        : !path.startsWith(".")
+        ? join(directory, path)
+        : null
+    )
+    .filter(Boolean)
+    .map((v) => v.replace(assetDir, ""));
+
+const listContent = (directory = srcDir) =>
+  readdirSync(directory)
+    .flatMap((path) =>
+      isDir(join(directory, path))
+        ? listContent(join(directory, path))
+        : !path.startsWith(".")
+        ? join(directory, path)
+        : null
+    )
+    .filter(Boolean)
+    .filter((f) => f.endsWith(".md"));
+const contentPath = (filename) =>
+  filename.includes(srcDir) ? filename : join(srcDir, filename);
+const contentUrl = (filename) =>
+  filename
+    .replace(/\//g, "-")
+    .substring(1)
+    .replace(/[\d]+_/g, "")
+    .replace(".md", "");
+const readContent = (filename, removeTags = false) => {
+  const content = readFileSync(contentPath(filename), encoding).trim();
+  return removeTags ? removeContentTags(content) : content;
+};
+const getTitle = (value) => value.replace("# ", "");
+
+const removeContentTags = (content) =>
+  content.replace(/\/[a-z]+\s\~(.*)\~/g, "");
+const isTag =
+  (key = "tag") =>
+  (value) =>
+    value.startsWith(`/${key}`);
+const getTag =
+  (key = "tag") =>
+  (value) =>
+    value.replace(`/${key} `, "").replace(/\~/g, "");
+const getTags = (content) =>
+  content
+    .match(/\/([a-z]+)\s\~(.*)\~/g)
+    ?.map((v) => ({
+      key: v.split(" ")[0].trim().replace("/", ""),
+      value: v.split(" ")[1].trim().replace(/\~/g, ""),
+    }))
+    .reduce(
+      (prev, { key, value }) => ({
+        ...prev,
+        [key]: [...(prev[key] || []), value],
+      }),
+      {}
+    );
+
+module.exports = {
+  encoding,
+  ROOT,
+  contentDir,
+  srcDir,
+  isDir,
+  mkdirs,
+  unique,
+  listContent,
+  contentPath,
+  contentUrl,
+  readContent,
+  getTitle,
+  removeContentTags,
+  isTag,
+  getTag,
+  getTags,
+  listAssets,
+  baseAssetRef,
+};

package/test.js

@@ -0,0 +1,4 @@
+const { loadIndex, loadPage, findPage } = require("./dist/index");
+
+console.log(loadIndex());
+console.log(loadPage(findPage("models-introduction")));