mdBook Integration for Innovation Cookbook

Summary

Integrated mdBook, an open-source Rust-based documentation engine, as a submodule to power our Innovation Cookbook, providing a robust foundation for technical documentation and knowledge sharing.
mdbook is the open source tool that powers the Innovation Cookbook. md-cookbook is the proprietary content that is IN the Innovation Cookbook.

Why Care

  • Leverages battle-tested open-source tooling for documentation
  • Separates content from presentation engine
  • Enables consistent documentation structure across projects
  • Maintains clean separation between open-source tool and proprietary content

Technical Details

Architecture Overview

  1. mdBook Integration
    • Added as a Git submodule tracking upstream directly
    • Maintains separation from other submodules' branching strategy
    • Preserves ability to contribute back to open source
  2. Innovation Cookbook Structure
    • Built on mdBook's rendering engine
    • Custom templates and themes
    • Organized for innovation documentation
    • Preserves proprietary content separate from engine

Implementation Notes

  • mdBook submodule tracks upstream main branch
  • Innovation content lives in separate repository
  • Clear separation between engine and content
  • Enables independent updates of both components

Impact and Usage

  • Documentation Team: Standardized tooling for technical writing
  • Developers: Familiar Markdown-based workflow
  • Organization: Clear separation of open source and proprietary content

Future Considerations

  • Monitor mdBook updates for new features
  • Consider contributing improvements back to open source
  • Evaluate additional mdBook plugins for enhanced functionality
  • Keep documentation structure aligned with innovation needs