Maglev Documentation

This repository contains the documentation site for Maglev, structured for clarity, extensibility, and ease of contribution. It is built on top of Sitepress and leverages Rails conventions, but introduces a custom structure for documentation content, components, and assets.

Project Structure

• pages/: Main documentation content, organized into:

  • guides/: Step-by-step guides and how-tos.
  • concepts/: Explanations of core concepts and data structures.
  • pro/: Pro features and advanced topics.
  • integrations/: Integration guides for third-party tools.
  • index.html.md: Main landing page for the docs.

• components/: View components for reusable UI elements.

  • app_layout/: Layout-related components (sidebar, topbar, navigation, etc.).
  • app_layout_component.*: Main layout component files.

• assets/: Static assets and frontend code.

  • images/: Logos, favicons, and documentation screenshots (with subfolder for page-specific images).
  • stylesheets/: CSS files, including Tailwind and code highlighting styles.
  • javascripts/: JavaScript files, including Stimulus controllers for interactive features.
  • config/: Asset pipeline configuration.

• liquid/: Custom Liquid tags and concerns for dynamic content rendering inherited from Gitbook

  • tags/: Custom tag implementations (e.g., code blocks, tabs, hints, descriptions).
  • tags/concerns/: Shared logic for tags.

• layouts/: HTML layout templates for the site.

• helpers/: Ruby helpers for view logic shared across pages and layouts.

• config/: Site configuration and initializers.

• scripts/: Ruby scripts for automation (e.g., generating markdown, search indexes, migrations).

• spec/: RSpec tests for custom tags and helpers.

Getting Started

1. Install dependencies:
   • Ruby gems: bundle install
   • JavaScript packages: yarn install

gem install foreman

2. Start the development server:

   foreman start -f Procfile.dev

   Then open http://127.0.0.1:8080 to view the docs locally.

3. Edit or add documentation:

   • Add or update markdown files in pages/.
   • Add images to assets/images/.
   • Update or create components in components/.

4. Compile for production:

   bundle exec rake compile

   The static site will be built in the ./build directory.

Contributing

• Follow the established structure for new guides, concepts, or integrations.
• Use components for reusable UI.
• Use Stimulus controllers for JavaScript interactions.
• Prefer Tailwind CSS classes for styling.

More Information

• For more on Sitepress, see https://sitepress.cc
• For Maglev documentation, browse this site or contribute via pull requests.