Website

GitLab: c2platform/website 

Welcome to the repository for the C2 Platform website, available at https://c2platform.org  . This site is built using Hugo  , a powerful static site generator, and styled with the with the Docsy Theme  , a documentation theme for technical documentation sites.

• Development Workflow
  • CI/CD Pipeline
• Getting Started
  • Prerequisites
  • Local Development
• Advanced Setup
  • PlantUML Server
  • Hugo in Podman Container
• Verification
• PlantUML support
• Pre-commit Hook
• Troubleshooting
• Links

Development Workflow

CI/CD Pipeline

Our CI/CD pipeline facilitates automatic builds and deployments:

1. Production Build: Commits to the master branch trigger a build and deployment to the main website at https://c2platform.org  .
2. Development Build: Commits to the development branch generate a preview version accessible at https://next.c2platform.org  .

Getting Started

Prerequisites

Ensure you have the following installed:

• Hugo (Extended Version): Required for local development.
• Node.js: Necessary for managing JavaScript dependencies.
• Git: For version control.

Local Development

To set up your environment and start contributing:

1. Install Dependencies: Make sure you have snapd and podman installed.

   sudo apt install snapd podman -y
   sudo snap install hugo
   

2. Clone the Repository:

   git clone git@gitlab.com:c2platform/website.git
   cd website
   

3. Install Node Version Manager ( NVM ) and NodeJS:

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh 
   
    | bash
   nano ~/.bashrc
   source ~/.bashrc
   nvm install 18
   npm install
   

4. Install JavaScript Dependencies:

   npm install
   

5. Start the Hugo Server:

   hugo server
   

Now, you can access the site at http://localhost:1313  and see your changes in real-time.

Advanced Setup

PlantUML Server

To use or view PlantUML diagrams locally, start a PlantUML server:

podman run -d -p 8080:8080 docker.io/plantuml/plantuml-server:tomcat

Hugo in Podman Container

Run the website in a Docker container without installing dependencies:

sudo apt install podman -y
podman run --rm -it -v $(pwd):/src -p 1313:1313 docker.io/klakegg/hugo:ext-ubuntu server

Verification

After starting the Hugo server or Docker container, visit http://localhost:1313 to view the site. Live reload is enabled, so changes you make will automatically reflect in the browser.

PlantUML support

This site supports PlantUML and Mermaid diagrams through Docsy. Note that for reliability, PlantUML diagrams are pre-rendered to PNG files during the CI/CD process. For more information about PlantUML and other diagrams, visit the Docsy documentation on diagrams  .

Pre-commit Hook

#!/bin/sh
rm -rf public || true
hugo
python3 scripts/htmldataproofer/ignore.py
python3 scripts/htmldataproofer/list.py
cd public
htmlproofer --allow-missing-href --ignore-empty-alt --ignore-missing-alt --no-enforce-https  2>&1 | tee ../htmlproofer.log
if grep -q "following failures were found" ../htmlproofer.log; then
    echo "Failures found. Exiting."
    exit 1
fi

Troubleshooting

If you encounter issues, consult the Docsy Example  project for common troubleshooting tips.

Links

• Pipelines 
• Docsy user guide 
• Docsy 
• example.docsy.dev 
• Hugo 
• Hugo theme module