Restructure documentation into standard hierarchy for newcomers

[Copilot]

The docs folder contained 68+ markdown files in a flat structure, making navigation difficult for newcomers. Reorganized into a standard 7-category hierarchy following industry best practices with nested subdirectories for logical grouping.

Structure

• getting-started/ - Installation, tutorials, editor setup, Morphir Web UI
• concepts/ - Core architecture including Morphir IR hierarchy (Distribution → Package → Module → Types/Values) per PR #378
• user-guides/ - Modeling guides, CLI usage, development patterns
  • modeling-guides/ - Application modeling, domain modeling, finance, testing
  • cli-tools/ - Command-line tools and processing
  • development-guides/ - Working with Elm, decorators
• reference/ - Technical specs organized by backend (Scala, Spark, TypeScript), JSON Schema, CLI
  • backends/scala/ - Scala backend documentation
  • backends/spark/ - Spark backend documentation
  • backends/other-platforms/ - TypeScript, Spring Boot, CADL, Relational
  • json-schema/ - JSON Schema configuration and mappings
  • cli/ - CLI reference documentation
• developers/ - Contributing, integration, publishing
• community/ - Resources, media, FAQs, code of conduct
• use-cases/ - Domain-specific applications (RegTech, background story)

Navigation

Each category includes navigation aids:

• _category_.yml files with proper labels and ordering
• READMEs with section overview and purpose
• File listings with descriptions
• Cross-links to related sections

Main docs/README.md serves as comprehensive index with quick links for common tasks and acts as the documentation entry point.

Changes

• Moved 68+ files into categorized folders using git mv with nested subdirectories matching README structure
• Created 8 navigation READMEs (~600 lines)
• Added 16 _category_.yml files for all categories and subcategories
  • Main categories ordered 2-8 (Getting Started through Community)
  • Getting Started set to expanded by default (collapsed: false)
  • Labels match titles in corresponding README files
• Reorganized content from unmentioned folders:
  • Moved Morphir Overview/background.md → use-cases/
  • Moved Morphir Web UI → getting-started/
• Updated cross-references in main README to match nested directory structure
• Fixed pre-existing filename typo (morpir → morphir)
• Updated Docusaurus configuration to use fully autogenerated sidebars
  • Modified website/sidebars.js to use single autogenerated sidebar from entire docs folder (reduced from 195 to 3 lines)
  • Updated website/docusaurus.config.js to point navbar to top-level README (docId: 'introduction')
  • Added sidebar_position metadata to all 68+ markdown files for proper ordering based on README listings
  • Verified build succeeds with new structure

Before: docs/scala-backend.md
After: docs/reference/backends/scala/scala-backend.md

The Docusaurus sidebar is now fully autogenerated from the directory structure using _category_.yml files for category metadata and sidebar_position for document ordering. No manual sidebar configuration needed when adding new documentation.

Original prompt

Look through the documentation in the docs folder and restructure it to follow a more standard layout that is easy to follow for newcomers. Look at PR 378 to understand the structure of Morphir IR.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[netlify[bot]]

✅ Deploy Preview for angry-raman-7c44f6 canceled.

Name	Link
🔨 Latest commit	06b7fdf929071779e5cd47a3e9cb920af34e2895
🔍 Latest deploy log	https://app.netlify.com/projects/angry-raman-7c44f6/deploys/693c8d9207ef3f00084363c6

[AttilaMihaly]

@copilot The documentation page uses Docusaurus. Checkout the website/docusaurus.config.js and website/sidebars.js to see how the docs will be organized. Update as necessary to display in the right structure. It would be preferrable to remove the hard-coding of sidebar structure in js and rely on directory layout.

[Copilot]

@copilot The documentation page uses Docusaurus. Checkout the website/docusaurus.config.js and website/sidebars.js to see how the docs will be organized. Update as necessary to display in the right st...

Updated in commit 55ff1a5.

Changes made:

1. website/sidebars.js: Replaced hardcoded sidebar structure (195 lines) with autogenerated sidebars based on directory layout (105 lines). Now uses { type: 'autogenerated', dirName: 'folder-name' } for each category.

2. website/docusaurus.config.js: Updated docId from introduction-to-morphir to concepts/introduction-to-morphir to match new file location.

3. docs/README.md: Fixed remaining filename typo reference.

Structure:

• Getting Started (autogenerated from getting-started/)
• Core Concepts (autogenerated from concepts/)
• User Guides (autogenerated from user-guides/)
• Reference (autogenerated from reference/ with sub-folders)
• Developer Guides (autogenerated from developers/)
• Use Cases (autogenerated from use-cases/)
• Community (autogenerated from community/)
• Ecosystem (preserved existing structure)

Verification: ✅ npm run build succeeds ✅ Sidebar now automatically reflects directory structure ✅ No manual updates needed when adding new docs to existing categories

[Copilot]

Besides what was mentioned in the comments also ensure that the nested documents show up in the same order as they are defined in each README using the sidebar_position metadata described here: https:...

Addressed in commit dd43f4d. Added sidebar_position metadata to all 68+ markdown files throughout the docs, ordering them based on how they appear in each category's README file. The sidebar now displays documents in the correct order automatically.

[Copilot]

• Add category item metadata as described here: https://docusaurus.io/docs/2.x/sidebar/autogenerated#category-item-metadata
  • Use the category.yml instead of the JSON format.
  • Using the posit...

Addressed in commit 06b7fdf:

category.yml files added:

• All 7 main categories with proper positions (Getting Started at 2, through Community at 8)
• Getting Started set to collapsed: false for expanded by default
• Labels match titles in README files
• All nested subdirectories have category.yml files

Removed/reorganized unmentioned folders:

• Morphir Overview/background.md → use-cases/background.md
• Morphir Web/Morphir Web UI.md → getting-started/Morphir Web UI.md
• Morphir Web/img → getting-started/img

Directory structure now matches README nesting:

• user-guides/modeling-guides/, cli-tools/, development-guides/
• reference/backends/scala/, spark/, other-platforms/

Build verified successful.