Migrate fineract-site to Hugo source workflow with containerized build, CI validation, and publish automation

[airajena]

Summary

This PR migrates fineract-site from manually maintained root HTML pages to a Hugo-based source workflow.

The migration introduces:

• Hugo source of truth under site-src/
• Data-driven homepage sections and reusable partials
• Security page migration into Hugo content/layout
• Containerized local build and serve scripts
• CI workflow for PR validation (build + link checks)
• Publish workflow for deployment branch updates

Why this change

The existing site structure relied on large hand-maintained HTML files that were hard to review and risky to edit. This migration improves maintainability and contributor velocity by:

• centralizing editable source in one structure
• reducing duplication via partials/templates
• standardizing local and CI builds with pinned container tooling
• preserving existing public URLs and static docs behavior

Scope of changes

1. Source of truth moved to Hugo

• Added site-src/config.toml
• Added Hugo layouts:
  • site-src/layouts/_default/baseof.html
  • site-src/layouts/_default/single.html
  • site-src/layouts/_default/security.html
  • site-src/layouts/index.html
  • site-src/layouts/404.html
  • site-src/layouts/partials/*
• Added data/content files:
  • site-src/content/_index.md
  • site-src/content/security.md
  • site-src/data/home.yml

2. Legacy root HTML cleanup

• Removed hand-maintained root pages from source editing path:
  • index.html
  • security.html
  • 404.html

3. Security page migration

• Migrated src/security/security.md into Hugo content path:
  • site-src/content/security.md
• Removed old security generation artifacts:
  • src/security/Makefile
  • src/security/Readme.md
  • src/security/favicon.html

4. Build and local developer workflow

• Added scripts:
  • scripts/site-build.sh
  • scripts/site-build.ps1
  • scripts/site-serve.sh
  • scripts/site-serve.ps1
  • scripts/check_internal_links.py
  • scripts/check-build.ps1
• Build output standardized to .build/site

5. CI/CD automation

• Added PR validation workflow:
  • .github/workflows/site-pr-check.yml
• Added publish workflow:
  • .github/workflows/site-publish.yml

6. Styling and UI parity work

• Kept existing visual direction while making styles maintainable
• Split/add navbar CSS in:
  • css/nav-styles.css
• Updated global and section styles in:
  • css/fineract.css
  • css/security.css

7. Contributor and repository docs

• Updated:
  • README.md
  • CONTRIBUTING.md
  • .gitignore
  • .htmlhintrc

URL and compatibility notes

• Preserved primary URL behavior:
  • /
  • /security.html
  • /404.html
  • /docs/... passthrough assets
• Static assets (css, js, images, font, docs) remain available via Hugo static mounts/output.

Testing performed

Local validation was executed using containerized scripts and repository checks:

1. Build

• ./scripts/site-build.sh --cleanDestinationDir
• ./scripts/site-build.ps1 --cleanDestinationDir

2. Local serve

• ./scripts/site-serve.sh
• ./scripts/site-serve.ps1

3. Link checks

• python ./scripts/check_internal_links.py --site-root .build/site

4. Visual verification

• Compared pre/post migration rendering for:
  • homepage section layout
  • navbar behavior on desktop/mobile
  • about/contribute/resources card and list styling
  • security page structure

Follow-up work (non-blocking)

• Further reduce duplicate or legacy CSS blocks in css/fineract.css
• Add stricter HTML/CSS linting gates if desired
• Continue iterative UI refinement while preserving migration architecture

[meonkeys]

Thank you! I'm reviewing this now.

[meonkeys]

for posterity: see FINERACT-2484

[meonkeys]

Please merge the latest from main into your branch. Apologies for the conflicts. I actually want to slim down CONTRIBUTING.md a bit (seems like a bit much boilerplate / common knowledge, and missing some stuff specific to maintenance of this repo), but I'll wait until you're done with this PR.

[airajena]

Please merge the latest from main into your branch. Apologies for the conflicts. I actually want to slim down CONTRIBUTING.md a bit (seems like a bit much boilerplate / common knowledge, and missing some stuff specific to maintenance of this repo), but I'll wait until you're done with this PR.

will try to simplify and keep focused docs for contributors , and resolve conflicts before final update.

[AliRana30]

Hi @meonkeys! As you suggested, here are my thoughts on the YAML maintainability question:

I agree with your concern about embedding HTML-heavy content in YAML (lines 156-158 of site-src/data/home.yml). It makes PRs harder to review and risks syntax errors. I'd recommend keeping structured data (versions, links, flags) in YAML but moving prose content (paragraphs with inline HTML) to Markdown files. This gives cleaner diffs, easier editing for non-technical contributors, and reduces the chance of breaking builds with YAML escaping issues.

What are your thoughts @airajena?

[airajena]

@meonkeys done with the changes

[meonkeys]

@AliRana30, thanks for your comments.

@airajena, this is awesome work! With this patch, project website dev will be fast, safe, and consistent/aligned with CI.

LGTM, except the failing checks. I'm getting ~60k lines of output about various things when I run checks, including stuff I don't care about (spaces vs. tabs in generated output) and spec-divergent HTML markup suggestions (always double-quote attributes). Before we merge I want all checks passing including htmlhint and axe. I'm fine with reducing the number of checks or removing them entirely. Your call how we resolve this.

I do prefer we run some sanity checks. Maybe Hugo does some/enough already--I don't know.

[airajena]

@AliRana30, thanks for your comments.

@airajena, this is awesome work! With this patch, project website dev will be fast, safe, and consistent/aligned with CI.

LGTM, except the failing checks. I'm getting ~60k lines of output about various things when I run checks, including stuff I don't care about (spaces vs. tabs in generated output) and spec-divergent HTML markup suggestions (always double-quote attributes). Before we merge I want all checks passing including htmlhint and axe. I'm fine with reducing the number of checks or removing them entirely. Your call how we resolve this.

I do prefer we run some sanity checks. Maybe Hugo does some/enough already--I don't know.

Thanks! Agreed on the signal/noise issue.

The current htmlhint/axe output is dominated by generated/static content and spec-style warnings that are not actionable for this repo, so I’ll simplify checks to keep CI useful and deterministic.

Plan:

• Keep required checks: Hugo build + internal link check.
• Remove htmlhint and axe from required build/check flow (can be reintroduced later in a scoped/optional way).

This keeps sanity checks in place while avoiding ~60k lines of low-value output. This is how I am thinking to resolve this

[meonkeys]

Sounds good.

[airajena]

Sounds good.

Done

[sonarqubecloud]

Quality Gate failed

Failed conditions
1 Security Hotspot
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[meonkeys]

After removing the prereqs for axe or htmlhint the fineract-site Docker image went from 1.28GB to 255MB for me. Nice

[meonkeys]

LGTM. 🚢

[airajena]

Thank you so much. @meonkeys
Please let me know if you have any improvements suggestions .

[meonkeys]

Thank you @airajena ! Great work.

I'm confused by [skip-publish] in the commit log message. What does that mean exactly?

[airajena]

I was a little confused by [skip-publish] in the commit log message. What does that mean exactly?

[skip-publish] is a tag in the commit message that tells GitHub Actions to not run the publish job for this commit. It’s used on the bot’s own publish commit so the workflow doesn’t trigger itself again and again.

Also I need permission to review the PR's for this repo. I can see some changes in CSS files in the draft PR, so need to add my comments if you allow.