Update/navigation #102
Open
Update/navigation #102
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Create nav-outline.md with proposed navigation structure - Update index.md with lifecycle-oriented navigation sections: - Starting or Releasing a Project - Maintaining, Supporting, and Enhancing - Growing and Sustaining a Project - References and Resources - Add section landing pages for each major category - Map existing content to new structure - Maintain backward compatibility with existing URLs This restructuring makes it easier for first-time open source releasers and long-time maintainers to find guidance relevant to their situation.
- Create reusable stub-template.md for consistent section landing pages - Enhance all section landing pages with standardized structure: - 'Who this is for' - Clear audience targeting - 'What you'll find here' - High-level content overview - 'Next steps' - Actionable links to child pages - Update content to match template requirements: - Starting: Focus on first-time open source releasers - Maintaining: Target active project maintainers - Growing: Address mature project needs - References: Provide quick access to tools and standards These stub pages provide clear orientation for newcomers and help users quickly identify the most relevant practices for their situation.
- Create content-migration-mapping.csv documenting the migration plan - Move practice pages to appropriate lifecycle sections: - Starting: community.md, releasing.md - Maintaining: maintaining.md, github-process.md, testing.md - Growing: (index.md only, content references existing sections) - References: (index.md only, content references existing sections) - Update all internal links to point to new file locations - Update front matter for moved files to reflect new navigation structure - Preserve repository management files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, CREDITS.md, LICENSE.md, README.md) in root directory - Update navigation links in section landing pages This migration improves content discoverability by organizing practices according to the project lifecycle while maintaining all existing functionality.
- Replace homepage with user-friendly landing page that guides visitors to relevant content - Create four distinct paths: - Starting Your First Project (primary path for beginners) - Maintaining an Existing Project (secondary path for active maintainers) - Growing and Sustaining (tertiary path for mature projects) - References and Resources (reference path for tools and standards) - Add visual styling with path cards, hover effects, and color-coded sections - Include call-to-action buttons for each section - Maintain mobile-responsive design - Preserve original homepage content as index-backup.md - Keep introduction content accessible at bottom of page This landing page makes the site more approachable for both beginners and seasoned maintainers by clearly directing them to relevant guidance.
- Create url-redirect-mapping.csv documenting all old to new URL mappings - Configure jekyll-redirect-from plugin in _config.yml - Add redirect_from front matter to all moved pages: - /community/ → /starting/community/ - /releasing/ → /starting/releasing/ - /maintaining/ → /maintaining/maintaining/ - /github-process/ → /maintaining/github-process/ - /testing/ → /maintaining/testing/ - Add homepage redirects for old documentation URLs: - /docs/ → / (new landing page) - /docs/index.html → / (new landing page) - Preserve all existing links and bookmarks - Ensure seamless user experience during transition This maintains backward compatibility while users and search engines adapt to the new lifecycle-oriented navigation structure.
dkotter
approved these changes
Sep 18, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description of the Change
This pull request introduces a major restructuring and modernization of the documentation site. It reorganizes content into clearer sections for starting, maintaining, and growing open source projects, adds new landing pages for these sections, updates the homepage to guide users by project stage, and improves navigation and plugin support. The most important changes are summarized below:
Site Structure and Navigation Overhaul
index.md) is redesigned to provide a more user-friendly, stage-based navigation with clear paths for starting, maintaining, and growing projects, including new visual cards and improved introductory content.maintaining/index.md), "Growing" (growing/index.md), and "GitHub Process" (maintaining/github-process.md) sections, each outlining who the section is for, what it covers, and next steps. [1] [2] [3]maintaining/maintaining.md) and testing (maintaining/testing.md). [1] [2]Content Organization and Migration
content-migration-mapping.csvfile is introduced to map current content to the new site structure, indicating where each document now lives and providing notes for repository management files.Configuration and Plugin Support
_config.ymlfile is updated to include thejekyll-redirect-fromplugin, enabling URL redirects for improved navigation and backwards compatibility.These changes collectively make the documentation easier to navigate, more maintainable, and better aligned with the needs of users at different stages of open source project development.
Closes #19.
How to test the Change
Visit: http://localhost:4000/Open-Source-Best-Practices/
Changelog Entry
Credits
Props @jeffpaul.
Checklist: