docs: parameterise documentation site

documentation/.env.example

@@ -0,0 +1,19 @@
+SITE_TITLE=Example
+SITE_TAGLINE=Example tagline
+SITE_LOGO_URL=img/grey-placeholder-image.png
+ORGANIZATION_NAME=Example Organizaion
+PROJECT_NAME=project-name
+FAVICON_URL=img/grey-placeholder-image.png
+HERO_IMAGE_URL=img/grey-placeholder-image.png
+HERO_IMAGE_ALT=Hero image alt
+NAVBAR_TITLE=NT
+EDIT_URL_BASE=https://example.com/link-purpose
+REPOSITORY_LINK=https://example.com/link-purpose
+SLACK_COMMUNITY_LINK=https://example.com/link-purpose
+ALT_TEXT_IMAGES=Generic image alt text
+SOCIAL_MEDIA_PREVIEW_IMAGE_URL=/img/un-crm-social-card.png
+EXTENSION_DOCS_LINK=https://example.com/link-purpose
+FOOTER_TITLE=Example Footer Title
+FOOTER_TEXT=Example Footer
+FOOTER_SPEC_TITLE=Example Specification
+FOOTER_SPEC_LINK=https://example.com/link-purpose

documentation/.gitignore

@@ -10,6 +10,7 @@
 
 # Misc
 .DS_Store
+.env
 .env.local
 .env.development.local
 .env.test.local

documentation/README.md

@@ -13,6 +13,10 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati
 $ yarn
 ```
 
+### Configuration
+
+By default, this project uses placeholder values for all required environment variables. You can start developing right away without any manual configuration. When you're ready to customize, you can adjust environment variables as explained in the [Environment Variables](#environment-variables) section.
+
 ### Local Development
 
 ```
@@ -35,6 +39,16 @@ This documentation site can be run in a Docker container. Below are the instruct
 
 ### Building the Docker Image
 
+By default, the Dockerfile sets these environment variables:
+
+```bash
+ENV PORT=3002 \
+    DOCS_URL=http://0.0.0.0 \
+    DOCS_BASE_URL=/
+```
+
+You can override these variables when running the container if needed.
+
 To build the Docker image, run the following command in the `documentation` directory of the project:
 
 ```bash
@@ -63,10 +77,28 @@ http://localhost:3002
 
 #### Environment Variables
 
-The following environment variables are set in the Dockerfile:
-
-- `PORT`: 3002 (The port on which the application will run)
-- `DOCS_URL`: http://0.0.0.0 (The URL for the documentation site)
-- `DOCS_BASE_URL`: / (The base URL for the documentation site)
-
-You can override these variables when running the container if needed.
+The site can be configured using environment variables found in the [.env.example](.env.example) file. Create a `.env` file in the same directory or set them directly in your environment.
+
+| Environment Variable             | Description                                    | Default Value                             |
+|----------------------------------|------------------------------------------------|-------------------------------------------|
+| `PORT`                           | Port on which the application runs             | `3000`                                    |
+| `DOCS_URL`                       | URL for the documentation site                 | `http://localhost`                          |
+| `DOCS_BASE_URL`                  | Base path for the documentation site           | `/`                                       |
+| `SITE_TITLE`                     | Title of the documentation site                | `Example Organization`                    |
+| `SITE_TAGLINE`                   | Tagline displayed on the site                  | `Example tagline`                         |
+| `SITE_LOGO_URL`                  | URL for the site logo                          | `img/grey-placeholder-image.png`           |
+| `ORGANIZATION_NAME`              | Name of the organization                       | `Example Organization`                    |
+| `PROJECT_NAME`                   | Name of the project                            | `Unnamed Project`                         |
+| `FAVICON_URL`                    | URL for the site favicon                       | `img/grey-placeholder-image.png`           |
+| `HERO_IMAGE_URL`                 | URL for the hero image                         | `img/grey-placeholder-image.png`           |
+| `HERO_IMAGE_ALT`                 | Alt text for the hero image                    | `Hero image`                              |
+| `NAVBAR_TITLE`                   | Title displayed in the navigation bar          | `Doc`                                     |
+| `EDIT_URL_BASE`                  | Base URL for edit links                        | `https://example.com/edit-url`            |
+| `REPOSITORY_LINK`                | URL to the project repository                  | `https://example.com/repo-link`           |
+| `SLACK_COMMUNITY_LINK`           | URL to the Slack community                     | `https://example.com/slack-community-link`|
+| `ALT_TEXT_IMAGES`                | Default alt text for images                    | `Unnamed alt text images`                 |
+| `EXTENSION_DOCS_LINK`            | URL to extension documentation                 | `https://example.com/extension-docs-link` |
+| `FOOTER_TITLE`                   | Title displayed in the footer                  | `Example Footer`                          |
+| `FOOTER_TEXT`                    | Text displayed in the footer                   | `Example Footer`                          |
+| `FOOTER_SPEC_TITLE`              | Title for the specification link in the footer | `Specification`                           |
+| `FOOTER_SPEC_LINK`               | URL to the specification documentation         | `https://example.com/footer-spec-link`    |

documentation/docusaurus.config.ts

@@ -1,19 +1,38 @@
 import type { Config } from '@docusaurus/types';
+import 'dotenv/config';
 import { themes as prismThemes } from 'prism-react-renderer';
 
 const url = process.env.DOCS_URL || 'http://localhost';
 const baseUrl = process.env.DOCS_BASE_URL || '/';
+const title = process.env.SITE_TITLE || 'Example Organization';
+const siteLogoUrL = process.env.SITE_LOGO_URL || 'img/grey-placeholder-image.png';
+const favicon = process.env.FAVICON_URL || 'img/grey-placeholder-image.png';
+const organizationName = process.env.ORGANIZATION_NAME || 'Example Organization';
+const projectName = process.env.PROJECT_NAME || 'Unnamed Project';
+const heroImageUrl = process.env.HERO_IMAGE_URL || 'img/grey-placeholder-image.png';
+const navbarTitle = process.env.NAVBAR_TITLE || 'Doc';
+const editUrl = process.env.EDIT_URL_BASE || 'https://example.com/edit-url';
+const slackLink = process.env.SLACK_COMMUNITY_LINK || 'https://example.com/slack-community-link';
+const repoLink = process.env.REPOSITORY_LINK || 'https://example.com/repo-link';
+const altTextImages = process.env.ALT_TEXT_IMAGES || 'Unnamed alt text images';
+const heroImageAlt = process.env.HERO_IMAGE_ALT || 'Hero image';
+const tagline = process.env.SITE_TAGLINE || 'Example tagline';
+const extensionDocsLink = process.env.EXTENSION_DOCS_LINK || 'https://example.com/extension-docs-link';
+const footerTitle = process.env.FOOTER_TITLE || 'Example Footer';
+const footerText = process.env.FOOTER_TEXT || 'Example Footer';
+const footerSpecTitle = process.env.FOOTER_SPEC_TITLE || 'Specification';
+const footerSpecLink = process.env.FOOTER_SPEC_LINK || 'https://example.com/footer-spec-link';
 
 const config: Config = {
-  title: 'UN Transparency Protocol Test Suite',
-  tagline: 'A comprehensive suite of tools for testing conformance to the UNTP Specification.',
-  favicon: 'img/favicon.ico',
+  title,
+  tagline,
+  favicon,
 
   url,
   baseUrl,
 
-  organizationName: 'uncefact', // Replace with your GitHub org/user name
-  projectName: 'tests-untp', // Replace with your repo name
+  organizationName,
+  projectName, 
 
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',
@@ -33,7 +52,7 @@ const config: Config = {
       {
         docs: {
           sidebarPath: './sidebars.ts',
-          editUrl: 'https://github.com/uncefact/tests-untp/tree/main/',
+          editUrl,
         },
         blog: false,
         theme: {
@@ -42,7 +61,7 @@ const config: Config = {
             require.resolve('./src/css/index.scss'),
           ],
         },
-      } 
+      }
     ],
   ],
 
@@ -51,18 +70,18 @@ const config: Config = {
   themes: ['@docusaurus/theme-mermaid'],
 
   themeConfig: {
-    slackLink:
-    'https://join.slack.com/t/uncefact/shared_invite/zt-1d7hd0js1-sS1Xgk8DawQD9VgRvy1QHQ',
-    repoLink: 'https://github.com/uncefact/tests-untp',
+    slackLink,
+    repoLink: repoLink,
     colorMode: {
       disableSwitch: true,
     },
-  image: 'img/un-crm-social-card.png',    
-  navbar: {
-      title: 'TP',
+    heroImage: heroImageUrl,
+    heroImageAlt,
+    navbar: {
+      title: navbarTitle,
       logo: {
-        alt: 'UNTP Test Suite Logo',
-        src: 'img/logo.svg',
+        alt: altTextImages,
+        src: siteLogoUrL,
       },
       items: [
         {to: '/docs/introduction', label: 'Introduction', position: 'right'},
@@ -76,27 +95,27 @@ const config: Config = {
           label: 'Tools and support',
           position: 'right',
         },
-        {to: 'https://uncefact.github.io/spec-untp/docs/extensions/', label: 'Extensions', position: 'right'},
+        {to: extensionDocsLink, label: 'Extensions', position: 'right'},
         {
-          to: 'https://github.com/uncefact/tests-untp',
+          to: repoLink,
           label: 'Contribute',
           position: 'right',
         },
         {
-          href: 'https://app.slack.com/client/T03KNUD7LHZ/C05R8DD2AKZ',
+          href: slackLink,
           position: 'right',
           html: '<svg class="icon icon-slack"><use xlink:href="#slack"></use></svg><span class="menu-item-name">Slack</span>',
           className: 'navbar-slack-link',
         },
         {
-          href: 'https://github.com/uncefact/tests-untp',
+          href: repoLink,
           html: '<svg class="icon"><use xlink:href="#github"></use></svg><span class="menu-item-name">Github</span>',
           className: 'navbar-github-link',
           position: 'right',
         },
-         {
-            type: 'docsVersionDropdown',
-          },
+        {
+          type: 'docsVersionDropdown',
+        },
       ],
     },
     footer: {
@@ -137,15 +156,15 @@ const config: Config = {
           ],
         },
         {
-          title: 'UN Transparency Protocol',
+          title: footerTitle,
           items: [
             {
-              label: 'UNTP Specification',
-              href: 'https://uncefact.github.io/spec-untp/',
+              label: footerSpecTitle,
+              href: footerSpecLink,
             },
             {
               label: 'Slack Channel',
-              href: 'https://app.slack.com/client/T03KNUD7LHZ/C05R8DD2AKZ',
+              href: slackLink,
             },
           ],
         },
@@ -154,12 +173,12 @@ const config: Config = {
           items: [
             {
               label: 'GitHub',
-              href: 'https://github.com/uncefact/tests-untp',
+              href: repoLink,
             },
           ],
         },
       ],
-      copyright: `© United Nations Economic Commission for Europe`,
+      copyright: `© ${footerText}`,
     },
     prism: {
       theme: prismThemes.github,

documentation/package.json

@@ -21,6 +21,7 @@
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "docusaurus-plugin-sass": "^0.2.5",
+    "dotenv": "^16.4.7",
     "prism-react-renderer": "^2.3.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",

documentation/src/pages/index.tsx

@@ -1,7 +1,6 @@
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import HomepageFeatures from '@site/src/components/HomepageFeatures';
-import HomeHeroImageUrl from '@site/static/img/home-hero.jpg';
 import Layout from '@theme/Layout';
 
 function HomepageHero() {
@@ -10,7 +9,7 @@ function HomepageHero() {
     <header className="home-hero">
       <div className="home-hero__container">
         <div className="home-hero__content">
-          <h1 className="home-hero__title">UN Transparency Protocol <br /> Test Suite</h1>
+          <h1 className="home-hero__title">{siteConfig.title} <br /> Test Suite</h1>
           <p className="home-hero__description">{siteConfig.tagline}</p>
           <div className="home-hero__actions">
             <Link
@@ -21,18 +20,19 @@ function HomepageHero() {
           </div>
         </div>
         <div className="home-hero__image-wrapper rad-10">
-          <img src={HomeHeroImageUrl} className="home-hero__image" alt="" />
+          <img src={siteConfig.themeConfig.heroImage as string} className="home-hero__image" alt={siteConfig.themeConfig.heroImageAlt as string} />
         </div>
       </div>
     </header>
   );
 }
 
 export default function Home() {
+  const {siteConfig} = useDocusaurusContext();
   return (
     <Layout
-      title="UN Transparency Protocol"
-      description="Supporting governments and industry on practical measures to counter greenwashing by implementing supply chain traceability and transparency at the scale needed to achieve meaningful impacts on global sustainability outcomes.">
+      title={siteConfig.title}
+      description={siteConfig.tagline}>
       <main className="homepage-content">
         <HomepageHero/>
         <HomepageFeatures/>

documentation/yarn.lock

@@ -4044,6 +4044,11 @@ dot-prop@^6.0.1:
   dependencies:
     is-obj "^2.0.0"
 
+dotenv@^16.4.7:
+  version "16.4.7"
+  resolved "https://registry.yarnpkg.com/dotenv/-/dotenv-16.4.7.tgz#0e20c5b82950140aa99be360a8a5f52335f53c26"
+  integrity sha512-47qPchRCykZC03FhkYAhrvwU4xDBFIj1QPqaarj6mdM/hgUzfPHcpkHJOn3mJAufFeeAxAzeGsr5X0M4k6fLZQ==
+
 duplexer@^0.1.2:
   version "0.1.2"
   resolved "https://registry.yarnpkg.com/duplexer/-/duplexer-0.1.2.tgz#3abe43aef3835f8ae077d136ddce0f276b0400e6"