Skip to main content

Google Docs Review Workflow

This document describes how to export documentation to Google Docs for collaborative review, then import the changes back to the repository.

Overview​

This workflow allows you to:

  1. Export a section of documentation (e.g., Islamic Banking) to a single markdown file
  2. Upload to Google Docs for collaborative editing
  3. Import reviewed changes back to the repository

Benefits:

  • ✅ Real-time collaboration with non-technical stakeholders
  • ✅ Track changes and comments in Google Docs
  • ✅ Preserve navigation structure and internal links
  • ✅ Maintain version control in Git

Prerequisites​

  • Node.js installed
  • Access to the documentation repository
  • Google account for Google Docs

Step-by-Step Workflow​

Step 1: Export Documentation​

Export a section of documentation to a review-friendly format:

node scripts/google-docs-export.js islamic-banking

What this does:

  • Reads all documents in the Islamic Banking section
  • Combines them into a single markdown file
  • Preserves hierarchical navigation structure
  • Converts internal links to trackable format
  • Creates table of contents
  • Outputs to exports/islamic-banking-review.md

Output location: exports/islamic-banking-review.md

Step 2: Upload to Google Docs​

  1. Go to Google Docs
  2. Click File > Open
  3. Click Upload tab
  4. Select exports/islamic-banking-review.md
  5. Google Docs will convert the markdown to a formatted document

Tips:

  • The document will have headers, links, and formatting preserved
  • Images will show as links (Google Docs limitation)
  • Internal document anchors create a clickable table of contents

Step 3: Share and Collaborate​

  1. Click Share button in Google Docs
  2. Add collaborators' email addresses
  3. Set permissions (Editor, Commenter, or Viewer)
  4. Collaborators can now:
    • Edit content directly
    • Add comments
    • Suggest changes (using suggestion mode)
    • Track revisions

Collaboration best practices:

  • Use Suggesting mode for changes (not direct editing)
  • Add comments for questions or discussions
  • Use version history to track major changes
  • Agree on final version before export

Step 4: Download Reviewed Document​

Once review is complete:

  1. In Google Docs, click File > Download
  2. Select Markdown (.md)
  3. Save to your local machine (e.g., downloads/islamic-banking-edited.md)

Note: Google Docs markdown export preserves most formatting but may need minor cleanup.

Step 5: Import Changes Back​

Import the reviewed document back to the repository:

node scripts/google-docs-import.js islamic-banking downloads/islamic-banking-edited.md

What this does:

  • Parses the combined document
  • Splits it back into individual files
  • Restores internal link format
  • Preserves original frontmatter (metadata)
  • Updates only the content portions
  • Reports which files were updated

Step 6: Review and Commit​

  1. Review changes:

    git diff

  2. Test locally:

    yarn start

    Navigate to the Islamic Banking section and verify changes

  3. Commit changes:

    git add docs/docs/*
    git commit -m "docs: update Islamic banking content from Google Docs review"

  4. Push to remote:

    git push origin your-branch-name

  5. Create pull request for team review

Supported Sections​

Currently configured sections:

  • islamic-banking - All Islamic Banking and Shariah-based deposit documentation

Adding New Sections​

To export other documentation sections, edit scripts/google-docs-export.js and scripts/google-docs-import.js:

const DOC_SECTIONS = {
  'islamic-banking': { /* existing config */ },
  'your-new-section': {
    name: 'Your Section Name',
    sidebarPath: 'sidebars/primary-sidebars.js',
    sidebarKey: 'Sidebar Label',
    outputFile: 'exports/your-section-review.md',
  },
};

Document Structure​

Export Format​

The exported document includes:

  1. Header

    • Title
    • Export date
    • Purpose statement

  2. Table of Contents

    • Hierarchical navigation
    • Clickable links to sections

  3. Document Content

    • All pages in navigation order
    • Preserved headings and formatting
    • Internal links converted to trackable format
    • Images as absolute URLs

  4. Footer

    • Document metadata
    • Re-import instructions

Document Markers​

The scripts use special markers to preserve structure:

  • <a name="doc-id"></a> - Document anchors for splitting on import
  • {{INTERNAL_LINK:doc-id}} - Internal link markers (converted back on import)
  • --- - Document separators

Important: Don't remove these markers when editing!

Handling Images​

During Export​

Images are converted to absolute URLs:

![Alt text](https://docs.mambu.com/img/image-name.png)

In Google Docs​

  • Images show as links (Google Docs limitation)
  • Reviewers can click to view images in browser
  • Image paths are preserved for re-import

During Import​

Image URLs are converted back to relative paths:

![Alt text](/img/image-name.png)

Export:

[Link text]({{INTERNAL_LINK:target-doc-id}})

Import:

[Link text](/docs/target-doc-id)

Preserved as-is in both directions.

Troubleshooting​

Export Issues​

Problem: "Could not find section in sidebar"

  • Solution: Check that the section name matches exactly in sidebars/primary-sidebars.js

Problem: "Could not find file for doc ID"

  • Solution: File may have been renamed or deleted. Check docs/docs/ directory

Import Issues​

Problem: "Import file not found"

  • Solution: Check file path is correct relative to project root

Problem: Document not split correctly

  • Solution: Ensure <a name="..."></a> anchors weren't removed during editing

Problem: Frontmatter lost

  • Solution: Import preserves original frontmatter from repository files

Google Docs Issues​

Problem: Formatting lost in upload

  • Solution: Google Docs markdown support is basic. Focus on content; formatting is preserved in repository

Problem: Can't download as markdown

  • Solution: Use File > Download > Markdown (.md), not "Plain text"

Best Practices​

Before Export​

  1. ✅ Ensure all documentation is up-to-date in main branch
  2. ✅ Commit any pending changes
  3. ✅ Create a dedicated branch for the review

During Review​

  1. ✅ Use Google Docs suggestion mode
  2. ✅ Add comments for complex changes
  3. ✅ Keep document structure intact
  4. ✅ Don't remove special markers (anchors, separators)
  5. ✅ Resolve all comments before final export

After Import​

  1. ✅ Review git diff carefully
  2. ✅ Test documentation site locally
  3. ✅ Check all internal links work
  4. ✅ Verify images display correctly
  5. ✅ Get peer review before merging

Limitations​

  • Images in Google Docs: Show as links only, not embedded
  • JSX Components: Converted to markdown equivalents (may need manual adjustment)
  • Complex formatting: May be simplified during Google Docs conversion
  • Large documents: Google Docs may be slow with 50+ page documents

Alternative: Partial Export​

For very large sections, you can export a subset by temporarily modifying the sidebar section in the script.

Security Considerations​

  • ⚠️ Exported files may contain internal documentation
  • ⚠️ Use Google Docs sharing permissions carefully
  • ⚠️ Don't share review docs publicly
  • ⚠️ Delete exported files after import

Support​

For issues or questions:

  1. Check this documentation
  2. Review script comments in scripts/google-docs-export.js and scripts/google-docs-import.js
  3. Contact documentation team

Version History​

  • v1.0 (2026-02-19): Initial workflow for Islamic Banking documentation