docs(get-started): add Cardano Developer Pathway with interactive Mermaid map

[danbaruka]

Updating documentation or Bugfix

This PR adds a Cardano Developer Pathway page under Get Started: a single overview with an interactive Mermaid flowchart that outlines typical learning and delivery paths (orientation, tracks, integration, testnets, and specialisations). Nodes use click targets to external docs and to this page where helpful.

Implementation notes

• New doc: docs/get-started/developer-pathway/overview.mdx, with diagram source in src/data/developer-pathway-chart.js and rendering via src/components/MermaidDiagramFrame (fullscreen, zoom +/- and 1:1 reset, Ctrl/Cmd + scroll zoom, theme-aware diagram background).
• Sidebar: Developer Pathway is listed fourth under Get Started (after Networks, Infrastructure, Client SDKs) in sidebars.js.
• Theme: src/theme/DocSidebarItems/index.js keeps all four Get Started siblings visible when viewing the pathway page (avoids Docusaurus hiding inactive categories so the item no longer looks “first” or alone).

Scope / content

• Intro and closing paragraphs kept short; former deep-link sections and “Explore further” were removed per iteration.
• Internal Mermaid click URLs point at the pathway doc (no orphaned anchors).

Please review wording and whether the pathway should stay MDX + custom frame or be simplified later.

[Ranchhand87]

Latest version reviewed and tested, PR should be left in /staging or moved to another branch while additional input is considered. Suggested Placement is a new folder (Menu Option) under 'Get Started'.

[katomm]

Hey, like said in the dev ex call, this is a great idea. A few comments on this PR.

The DocSidebarItems override (src/theme/DocSidebarItems/index.js) is the main thing that gives me pause. It overrides a core Docusaurus component just to keep sibling items visible, and it relies on hardcoded checks for the "Networks" label and the pathway doc ID. This will likely break on Docusaurus upgrades without warning. Could this be solved by restructuring the sidebar config instead? For example, making Developer Pathway a category with a link doc (like Client SDKs already does) would avoid the swizzle entirely. (Swizzle something is risky and should be last resort)

A lot of the click links go nowhere useful as the Mermaid click targets point back to /docs/get-started/developer-pathway/overview/ (the page you're already on)

The frontmatter references image: /img/og/og-getstarted-overview.png but the file isn't included in the PR.

[katomm]

Hey @Ranchhand87 should this be merged to staging or to a different branch? I'm asking because of the "PR should be left in /staging". If something is in staging then it will land in main soon after. If we want to work on this on a different branch then @danbaruka should make the PR against the other branch.

[danbaruka]

Hey @katomm,

Thanks for the feedback.

I’ve addressed the previous comments:

• Removed the DocSidebarItems override and restructured the sidebar config
• Fixed the Mermaid links so they point to the correct pages
• Added the missing image asset

Everything should be updated now. We can go ahead and merge this into staging.

Let me know if anything else needs adjustment.
Cc: @Ranchhand87

[Ranchhand87]

Hey @Ranchhand87 should this be merged to staging or to a different branch? I'm asking because of the "PR should be left in /staging". If something is in staging then it will land in main soon after. If we want to work on this on a different branch then @danbaruka should make the PR against the other branch.

If the mechanics have not been decided RE: Where this fits in the Portal Infrastructure, then it should be pushed a 'given' or New branch for continued work.

Ideally, as long as you @katomm comments are addressed, I would love to see this up on the Portal. We could even add an in draft label. The goal here is to get it published, but also to work together without overstepping. Happy to grab a quick call as needed to make a clearer decision.

[0xBora]

Hey @danbaruka, thanks for sticking with this and for the work on the iterations. The MermaidDiagramFrame itself is is functional with zoom, fullscreen etc. . I do have a few things I'd like to talk through here though, and most of them are more about direction than line-level details.

Regarding line-level details, after pulling the branch and running the dev server, the Get Started section in the sidebar renders Networks, Infrastructure, Client SDKs and Developer Pathway twice each, eight children instead of four. Looking at sidebars.js, the new flat type: "link" shortcuts were added at the top of the items array but the original categories are still there underneath, so both end up rendering.

This is the kind of thing thats immediately visible on localhost and an important reminder that running the dev server locally to check as a last step before pushing contributions is important. A couple of related tidy-ups worth doing in the same pass, the new Developer Pathway category only contains itself as its single child, so a flat doc entry would be a cleaner approach than a category wrapping one item.

I see after @katomm's remarks there was an update to the swizzled components. But I still see a src/theme/DocSidebarItems/ directory now which only holds a small README noting that the swizzle was removed, which does not make sense. Since the swizzle was both added and removed inside this PR, from staging's point of view the directory shouldn't exist, so removing it entirely would be tidier than leaving a stub behind that documents a change which never happened from the staging branch perspective.

The bigger thing I want to raise is the click targets. Walking through them node by node, a lot of them don't actually land on what the node label promises. EVM-to-Cardano one ("accounts vs UTxO, no msg.sender, ExUnits vs gas") drops you on the Aiken homepage. The CBOR node goes to the generic transactions overview, which doesn't cover CBOR. The UTxO concurrency one (batching, beacons, fan-in fan-out) sends you to the smart-contracts landing page. testLayer, debugLayer, auditFirm, defiPath all funnel into the same few broad pages. The start node still points back to the page the reader is already on. I think when most clicks land on something more generic than what the label promised, the interactivity stops adding value and starts working against the page, the reader gets told "this isn't actually what I clicked on" enough times that the whole pathway feels less trustworthy.

And then there's the longer-term side, which is the part I'd most like your view on. The chart names a lot of specific tools, Mesh, Lucid, Blaze, Yaci, Blockfrost, Koios, Maestro, Aiken, OpShin, Helios, Plu-ts, specific CIPs, specific audit firms, ecosystem claims like default stack 2026. As all of these references can easily drift inside a year, Im not sure who'd own keeping a sixty-node flowchart in sync as the ecosystem moves. I think this node diagram and the intent behind it can translate its main purpose better by proposing changes to how developer portal is structured and how we are taking specific reader audiences through different sections. Maybe instead of adding this custom page and the complexity its more productive to go through the existing content and propose changes to serve these audiences better.

Docs that age badly can be worse than no docs because the reader can't tell which parts are still current. On top of that, between three phases, six specialisation paths, dotted cross-links and loop-back arrows, I think the flow sequences would have to be clearer if this interactive diagram is supposed to be an overview. A couple other observations: there's no shared terminology defined for "phase" vs "track" vs "ramp" vs "specialisation," and a few of the node descriptions are short to the point of being hard to parse and understand the meaning of. Especially thinking that this diagramme is supposed to help "outsiders" who are not familiar with Cardano terminology, there surely is a lot of Cardano specific technology & words utilized. As its mostly discussed in #1758, #1738 and our developer experience sessions, its better if we try to reframe existing content or any new contribution to be tool/technology agnostic and follow concepts. I think many nodes in the diagram fail at this and could definitely be better.

MermaidDiagramFrame adds a custom component to the portal which carries a maintenance cost across future Docusaurus upgrades and accessibility passes. So we should ensure the value added side has to be pretty clear. I want us to think a bit longer-term about who maintains this, whether the artefact carries enough meaning to justify the surface area, and whether the same intent could be delivered more simply before we commit to a custom component and reshape the sidebar around it. If the goal is surfacing different paths for different audiences (beginner, Web2 dev, EVM dev, designer) which sounds valuable, I'd still lean towards solving it by writing content for those audiences first. A simple markdown page with proper sections per profile and links that actually point at the specific topic named, with prose doing the explaining. If that page proves its weight once it's live and people are using it, we can revisit whether a visual map adds something the prose doesn't, and at that point look at whether a custom component is the right way to render it.

This means we earn the maintenance cost rather than taking it on upfront.

Given these, I'd rather not merge this into staging in its current state. Happy to hear back about it.

[danbaruka]

Understood, thanks for the thorough review, @0xBora. Working through the fixes now.

[danbaruka]

Hey @0xBora, thanks for the thorough review. Pushed an update.

Sidebar is cleaned up: duplicated link shortcuts gone (Get Started shows four children now), the single-item Developer Pathway category is now a flat doc entry, and src/theme/DocSidebarItems/ is deleted.

Removed every click directive in the chart, so the diagram is now purely informational and can't land you somewhere that doesn't match the label.

Every named tool, SDK, indexer, API provider, audit firm, and specific CIP number is replaced with a category label (API provider, Indexer: chain data and queryable store, JavaScript or TypeScript SDK, etc.). The "Default stack 2026" anchor is gone too. Specific recommendations live in their dedicated docs pages so the chart doesn't need re-editing as the ecosystem moves.

Added a "How to read this diagram" section defining Phase, Track, Ramp, and Specialisation.

Deleted src/components/MermaidDiagramFrame/ entirely. The page now uses Docusaurus's native @theme/Mermaid directly, so there's no added maintenance surface across Docusaurus upgrades or accessibility passes. Trade-off is we lost the zoom and fullscreen toolbar, happy to revisit if usage shows it's needed. Also fixed the Phase header overlap with a Mermaid init directive.

Cc: @Ranchhand87

[Ranchhand87]

It looks like things are in a good place, here are a few notes for adjustment/discussion as appropriate.

• Left Menu, Most menu items are greyed out, Get Started shows highlighted, then the sub-page, then the sub-sub page. These highlights are all the same color and at first light cause some confusion. My suggestion is to highlight on the page that the user is actually on, or to change the highlight scheme (back up the ladder) when going into the sub pages.
• Networks: As I read through, it kinda seems distracting to change format mid-page, Suggestion is to follow the established 3 columns as set by the table. Going into paragraphs made me think we were just going to discuss mainnet, then I read into testnets without the proper frame of reference. Further adding to confusion is 'Testnets' having its own sub-sub page.
• Yaci-devkit: This is a tool to run a dev network as opposed to an actual accessible development network like cardano testnet. This should be adjusted, other tools should likely be added. I would suggest reframing this page and/or bundling differently under 'testnets'. This may be a scenario of sub page nesting dolls.
• Varied naming of 'Titles' between yaci and testnet. This should likely follow a simplified look. ex: 'Yaci-Devkit' and 'Test Custom Clusters Locally With cardano-testnet'
  --It should simply be Yaci Devkit and cardano-testnet, but again, Yaci Devkit may be due to be moved.
• Infrastructure: In the chart below the graphic, I would suggest adjusting from 'Own Node' to User Node or Owner Node, something that would naturally make more sense. The current format feels/reads as bare minimum succinct-ion.
• Infrastructure (Graphic): When it says Cardano Networks, I believe this would be a safe link back to the top-level, Potentially adding sub-text could be helpful to the reader as well (preview, pre-prod, mainnet, sanchonet, etc.)
• We seem to jump directly to Demeter, are there other options? Should we also consider keeping the Tabular format on this page?
• Sub-sub page explosion again, It may be relevant, reading on.
• Order of Sub-pages, API-Providers, then Node, then Demeter (this varies from the flow at the 'top' level.

sub-sub-sub+ here. - Is there a CTA back to the frame of this addition? Feels like we can get really truly lost with these sub-menus. Happy to have a call to discuss, maybe a few min in OSC? - Wallets should probably move to a different page-set to live as a forever (more easily findable/updateable) reference. - Did we move away from single click (from graphic) for Developer Pathway? I feel like users would be searching before finding the enlargement link in the Right column.

I believe this contains all of the relevant feedback in this PR. I actually may have gone above and beyond. @0xBora @katomm Did I misunderstand the OG format aside from the page(s) additions?

[0xBora]

Thanks for the iterations here @danbaruka. Some of the earlier feedback seems to be addressed.

Separately, the branch also changes the analytics setup in docusaurus.config.js, swapping the gtag config for the Google Tag Manager plugin. That is unrelated to this page and carries its own privacy and review implications, so please drop it from this PR. If there is fix there, it should go in its own PR as its a change that should not find its way in from a documentation update.

developer-portal/docusaurus.config.js

Lines 131 to 134 in 2c7175c

	// Google Tag Manager (use containerId GTM-… — not the gtag plugin, which expects a GA4 G-… ID)
	googleTagManager: {
	containerId: "GTM-5NM3NX4",
	},

[0xBora]

Thanks for the iterations @danbaruka, a lot of the earlier line-level feedback is addressed.

My call on direction is unchanged though, and it's less about this PR's internals than about where the portal now sits. Since this opened we shipped the Portal 2026 restructure, which set out to do the same thing this page aims at, giving developers a clearer, more easier to navigate path that is largely self-explanatory through the sidebar and navigation on their own.

The click targets were removed in the last iteration, so the diagram is now a static directory which gives an overview of words/terminology rather than something that routes people into the docs (which would be a huge maintenance surface), which was the argument why it could justify a dedicated page. The direction we've been converging on in #1758, #1738 and the dev experience sessions is to keep content concept-led and tool/technology agnostic, serving specific audiences by shaping the existing structure rather than adding a parallel artifact on top of it.

If we find the restructured nav isn't serving a specific audience well (Web2, EVM, designer), I'd rather fix that in the content and structure directly, and revisit a visual map only if that gap is still there. Otherwise it seems unproductive to me as its creating abstraction levels on a core problem that would need identification and solutions in the onboarding path.

[0xBora]

Feedback given in previous comments, updating PR status to requesting changes.