Skip to content

README

Jump to bottom
Norm Brandinger edited this page Nov 20, 2025 · 1 revision

Wiki Setup Instructions

This directory contains wiki content for the DevStack Core GitHub repository.

How to Upload to GitHub Wiki

GitHub wikis are separate Git repositories. Follow these steps to upload the wiki content:

Method 1: Clone and Copy (Recommended)

# 1. Clone the wiki repository
git clone https://github.com/NormB/devstack-core.wiki.git

# 2. Copy wiki files
cp ~/devstack-core/wiki/*.md devstack-core.wiki/

# 3. Commit and push
cd devstack-core.wiki/
git add *.md
git commit -m "Add comprehensive wiki documentation"
git push origin master

Method 2: Manual Upload via GitHub UI

  1. Go to https://github.com/NormB/devstack-core/wiki
  2. Click "New Page" for each wiki page
  3. Copy content from each .md file
  4. Use the exact filename (without .md) as the page title
  5. Save each page

Page Naming Convention

GitHub wiki converts filenames to page titles:

  • Home.md → "Home"
  • Quick-Start-Guide.md → "Quick Start Guide"
  • Common-Issues.md → "Common Issues"

Wiki Pages Included

Essential Pages

  1. Home.md - Wiki homepage with navigation
  2. Quick-Start-Guide.md - 5-minute setup guide
  3. Architecture-Overview.md - System architecture
  4. Common-Issues.md - Troubleshooting guide
  5. Management-Commands.md - Complete command reference
  6. Reference-Applications.md - API implementation guide

Additional Pages to Create

You can expand the wiki by creating these pages based on existing documentation:

  1. Installation.md - From docs/INSTALLATION.md
  2. Vault-Integration.md - From docs/VAULT.md
  3. Service-Configuration.md - From docs/SERVICES.md
  4. Testing-Guide.md - From tests/README.md
  5. Best-Practices.md - From docs/BEST_PRACTICES.md
  6. Performance-Tuning.md - From docs/PERFORMANCE_TUNING.md
  7. Security-Hardening.md - From docs/SECURITY_ASSESSMENT.md
  8. Observability-Stack.md - From docs/OBSERVABILITY.md
  9. Environment-Variables.md - From .env.example with explanations

Creating Additional Wiki Pages

To convert existing documentation to wiki pages:

# Example: Create Installation wiki page
cp docs/INSTALLATION.md wiki/Installation.md

# Edit to add wiki-style navigation links
# Then upload to wiki repository

Wiki Navigation Best Practices

Each wiki page should include:

  1. Title - Clear H1 heading
  2. Table of Contents - For longer pages
  3. Internal Links - Link to related wiki pages using: [Page Title](Page-Title)
  4. External Links - Link to repository docs where appropriate
  5. "See Also" section - Related pages at the bottom

Maintaining the Wiki

Keep Wiki in Sync

The wiki should be supplementary to the main repository documentation:

  • Wiki: Quick reference, tutorials, FAQs
  • Repo docs/: Comprehensive, detailed, version-controlled

Update Process

  1. Make changes to wiki/*.md files
  2. Commit to main repository
  3. Push to wiki repository
# Update wiki
cd devstack-core.wiki/
cp ~/devstack-core/wiki/*.md .
git add *.md
git commit -m "Update wiki documentation"
git push origin master

Troubleshooting

Wiki Not Showing Up

  • Ensure wiki is enabled in repository settings
  • Go to Settings → Features → Wikis (enable)

Cannot Clone Wiki

# If wiki doesn't exist yet, create first page via UI
# Then clone will work
git clone https://github.com/NormB/devstack-core.wiki.git

Links Not Working

  • Use wiki-style links: [Page Title](Page-Title) not [title](page-title.md)
  • GitHub auto-converts filenames to title case
  • No .md extension in links

Wiki vs Documentation

Feature Wiki Repository Docs
Purpose Quick reference, tutorials Comprehensive documentation
Version Control Separate repo Main repository
Editing Web UI or Git Code editor
Search GitHub search Full-text search
Best For FAQs, guides API docs, architecture

Support

If you have questions about the wiki:

  1. Check existing pages for formatting examples
  2. See GitHub Wiki Documentation
  3. Open an issue in the main repository

Quick Commands

# Clone wiki
git clone https://github.com/NormB/devstack-core.wiki.git

# Update wiki content
cd devstack-core.wiki/
cp ~/devstack-core/wiki/*.md .
git add *.md
git commit -m "Update wiki"
git push

# View wiki
open https://github.com/NormB/devstack-core/wiki

Clone this wiki locally