Docusaurus v3

[mttrbrts]

Outstanding Tasks 🛍️

• After upgrading Docusaurus (Upgrade to Docusaurus and Migrate to vNext #505) the home page design is broken.
• Fix all broken links
• Sense check Template Playground examples
• Review all tutorials, and code snippets for accuracy
• Update images to remove references to Ergo

Use Case

Possible Solution

Context

Detailed Description

[ayyagarisujanreddy123]

I can work on this Issue.

[ChinmayaBiswal7]

Hi @mttrbrts 👋

I’d like to work on this issue.

From my understanding, this task involves addressing post-upgrade inconsistencies after migrating to Docusaurus v3, including UI breakage, broken links, outdated examples, and content cleanup (e.g., removing legacy references to Ergo).

Here’s the approach I’m planning to take:

1> Homepage design fixes

Run the project locally and compare the current homepage with the expected layout.

Inspect for layout regressions caused by Docusaurus v3 changes (theme config, layout components, CSS class changes, etc.).

Fix styling or component issues while keeping consistency with the updated v3 structure.

2> Broken links

Run a production build to identify broken link warnings.

Systematically audit internal doc links, navbar items, sidebar references, and relative paths.

Ensure routing aligns with Docusaurus v3 conventions.

3> Template Playground examples sanity check

Review examples referenced in documentation.

Verify correctness against the current Template Playground behavior.

Update outdated snippets if APIs or behavior have changed.

4> Tutorial and code snippet review

Audit tutorials for accuracy and consistency with the latest stack.

Validate code blocks for correctness.

Flag any larger architectural inconsistencies if found.

5> Update images (remove Ergo references)

Search repository for legacy references.

Replace screenshots or diagrams as needed.

Ensure branding consistency throughout the site.

Before I begin, I have a few quick clarifications:

Is there a reference deployment (e.g., staging/production site) I should use for visual comparison?

Should homepage styling strictly match pre-v3 layout, or are minor layout improvements acceptable?

For Template Playground examples — is manual validation sufficient, or is there an automated way to verify correctness?

Are there any known sections that require extra attention?

If this approach aligns with expectations, I’m happy to start by tackling the homepage and broken links first, then move systematically through examples and tutorials.

Looking forward to your feedback 🙂

[mttrbrts]

Is there a reference deployment (e.g., staging/production site) I should use for visual comparison?

Yes, see https://docs.accordproject.org/

Should homepage styling strictly match pre-v3 layout, or are minor layout improvements acceptable?

It should be similar, but some small layout and styling changes are allowed. E.g. title bar can follow the new v3 layout,

Also see the Concerto docs which have already been upgraded
https://concerto.accordproject.org/

For Template Playground examples — is manual validation sufficient, or is there an automated way to verify correctness?
Are there any known sections that require extra attention?

Template Playground is still a work in progress, and so some features may not yet be available.

Similarly, the templates at templates.accordproject.org, have not yet been migrated to use the new template-engine (i.e. to remove ergo). That's fine for now, I want to do that migration in parallel.

@ayyagarisujanreddy123 @ChinmayaBiswal7 I'm happy for you both to work on this, but please create sub tasks and assign yourself to avoid duplication.

[ChinmayaBiswal7]

Hi @mttrbrts , thanks for the clarification!

To avoid duplication, I suggest splitting the work into the following subtasks:

Subtasks:

Homepage layout fixes (Docusaurus v3 styling adjustments)

Broken internal links (docs, sidebar, navbar)

Image updates (removal of Ergo references)

Tutorial and code snippet review

Template Playground example validation

I’d like to take ownership of:

Homepage layout fixes

Broken internal links

Once those are complete, I can move on to image updates.

Please let me know if that division works.

[yuanglili]

@ayyagarisujanreddy123 @ChinmayaBiswal7 @mttrbrts Hi everyone I’m new here and I’d love to help with this. Thanks a lot for the breakdown. it looks really clear and feels like a great way to get started.
Could you share what each of you is currently working on? I’m happy to take on any remaining subtasks to avoid duplication. Thanks!

[ospreyboi]

hi @mttrbrts and everyone else. I'm new here and saw this issue yesterday.had started to work on this issue yesterday and up untill now i have fixed the duplication and case sensitive parts and few broken links
@ayyagarisujanreddy123 and @ChinmayaBiswal7 could you both connect and tell what all has been fixed on your ends? So that duplication on our part is reduced and rectified

[ChinmayaBiswal7]

hi @ospreyboi
I am working on Homepage layout fixes and Broken internal links

[yuanglili]

Hi everyone, I am working on Update images to remove references to Ergo and Review all tutorials + code snippets for accuracy. I’ll focus on these two areas and open a PR once I have a clean set of changes.

[mttrbrts]

@ChinmayaBiswal7 @yuanglili @ayyagarisujanreddy123 @ospreyboi

There's a draft PR here with an upgrade set of templates using the latest libraries.
accordproject/cicero-template-library#484

Please use this for reference / validation as required.

[ChinmayaBiswal7]

Hi @mttrbrts 👋

I've been working on the Homepage layout fixes and Broken internal links subtasks as mentioned earlier.

Here's what I've completed locally (branch ready):

Homepage (Docusaurus v3 fix)

Added full homepage CSS to

custom.css
— hero gradient, buttons, features section, content blocks, responsive layout
Replaced Ergo feature card with TypeScript/Template Logic (aligned with cicero-template-library#484)
Updated Logic section: Ergo → TypeScript description + image
Broken Links

Fixed /docs/model-concerto → concerto.accordproject.org/docs/intro
Fixed empty fixed rate loan link
Broken Images

Fixed 4 broken image paths in

started-hello.md
and

tutorial-library.md
(Docusaurus v3 uses relative paths)
Tutorial updates (aligned with cicero-template-library#484)

tutorial-templates.md
,

tutorial-library.md
,

tutorial-create.md
updated: logic.ergo → logic.ts, cucumber → vitest
May I open a PR against the mr-remove-ergo branch with these changes?

[yuanglili]

@mttrbrts
Quick question about “Update images to remove references to Ergo”: I’ve removed the Ergo images and the Ergo block on the homepage（/website/pages/en/index.js）
Should I also remove all Ergo-related docs/content, or is this task only about images/branding? Most remaining references seem to be under: /website/versioned_docs/version-0.12/

[ospreyboi]

Hi @mttrbrts
i have fixed all broken links

[ChinmayaBiswal7]

Hi @mttrbrts 👋

Just a quick update — I’ve already completed the Broken Internal Links fixes and verified them locally earlier.

The following links were corrected:

• /docs/model-concerto → https://concerto.accordproject.org/docs/intro
• Fixed the empty fixed rate loan link

All links are now working correctly in the docs.

Please let me know if you'd like me to open a PR for these fixes or if any additional changes are required.

[mttrbrts]

Hi all, thanks for your updates!

@yuanglili

the historical Ergo content in the versioned_docs folder should remain for reference, we should only need to update the latest (next) version of the docs

@ospreyboi @ChinmayaBiswal7

Please open a PR against the mr-remove-ergo branch. It sounds like theres some overlap with your work unfortunately. I'll attempt to reconcile when I review the PRs.