docs: restructure, clarify, consolidate existing docs #1726
Conversation
This file contains 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
…ity providers - Corrected links in existing documentation to point to the updated paths. - Removed the identity providers category file as it is no longer needed. - Added new integration guides for Apple, Auth0, Azure, Cognito, GitHub, GitLab, Google, OIDC, Okta, OneLogin, and Ping. - Included images and examples for each integration to enhance clarity and usability. - Updated the quick start references across multiple guides to reflect the new structure. This commit enhances the onboarding experience for users integrating with various identity providers and ensures all links are current.
…rprise guides - Corrected links across multiple documentation files to point to the updated '/deploy/enterprise' paths. - Added new guides for Pomerium Enterprise, including installation, configuration, and metrics. - Introduced new images and examples to enhance clarity in the documentation. - Created new files for managing clusters, JWT verification, and mutual authentication. - Removed outdated references and ensured all links are current for a better user experience. This commit improves the onboarding process for users and ensures that all documentation is aligned with the latest deployment structure.
…ines - Consolidated the 'Community' category in the sidebar to streamline navigation, commenting out the section for future reference. - Enhanced the 'What is Pomerium?' documentation by expanding the description and adding key benefits and operational details. - Removed the 'Code of Conduct' and 'Contributing' documents to simplify the community section, as they are no longer needed. - Deleted associated images that were part of the removed documents. This commit improves the clarity and accessibility of the documentation while ensuring that outdated content is removed for a better user experience.
- Consolidated and commented out the 'Pomerium Zero' and 'Pomerium Core' categories in the sidebar for future reference, while introducing a new 'Deploy' category to streamline navigation. - Updated image paths in the recovery token documentation for better organization. - Removed the outdated 'Community' documentation and added new guides for Pomerium Enterprise, including installation, configuration, and troubleshooting. - Introduced new integration guides for external data sources and enhanced existing documentation with additional examples and images. - Added troubleshooting information for common configuration issues and clarified the process for generating recovery tokens. This commit improves the clarity, accessibility, and usability of the documentation, ensuring users have the most up-to-date information for deploying and managing Pomerium.
- Changed all instances of the Pomerium Docker image from specific version tags (v0.27.2 and v0.28.0) to the 'latest' tag across multiple documentation files. - This update ensures users are directed to use the most current version of Pomerium for deployment, enhancing the overall user experience and reducing potential issues with outdated images. This commit improves the clarity and usability of the documentation by promoting the use of the latest available resources.
- Commented out the 'Kubernetes' category in the sidebar for future reference while introducing a new 'Deploy' category to improve navigation. - Updated image paths in the device identity documentation for better organization. - Added new files for Kubernetes configuration, including global settings, ingress setup, and quickstart guides. - Introduced new images to enhance clarity and usability in the documentation. - Removed outdated images and files related to previous versions and community guidelines. This commit improves the clarity, accessibility, and usability of the documentation, ensuring users have the most up-to-date information for deploying and managing Pomerium in Kubernetes environments.
… security policy page - Deleted the standalone 'cryptography.md' file to streamline documentation. - Integrated essential cryptography details into the 'security.md' file, enhancing the security policy with comprehensive information on encryption in transit and at rest. - Updated the title and keywords of the security policy to reflect the inclusion of cryptography topics. This commit improves the organization and accessibility of security-related information, ensuring users have a consolidated resource for understanding Pomerium's security measures.
- Updated the 'certificates.mdx' file to change references for zero trust principles from the concepts section to the internals section. - Deleted the 'cluster-status.mdx' file, consolidating its content into the 'clusters.mdx' file, which now includes a comprehensive troubleshooting section for cluster status alerts. - Enhanced the 'clusters.mdx' file with detailed explanations of various cluster status alerts, their causes, and resolution steps. This commit improves the organization and accessibility of cluster management documentation, ensuring users have a consolidated resource for troubleshooting cluster health issues.
…ication services - Removed the 'Hosted Authenticate Service' documentation and integrated its content into the 'Authentication' section, streamlining the information for users. - Added new documentation for non-HTTP protocols, including TCP and UDP, detailing how to tunnel these connections through Pomerium. - Created examples for various services (e.g., Redis, MySQL, PostgreSQL, RDP, and SSH) to demonstrate how to establish secure connections using Pomerium's CLI and Desktop clients. - Introduced a new 'Custom Domains' guide for Pomerium Zero, explaining how to set up and manage custom domains effectively. - Updated existing documentation to reflect the latest changes and improve clarity, ensuring users have access to comprehensive and organized resources. This commit enhances the usability and accessibility of the documentation, providing users with clear guidance on utilizing Pomerium for non-HTTP services and authentication management.
- Consolidated and updated sidebar entries for capabilities, including renaming and reorganizing sections for clarity. - Introduced new documentation for 'Certificates and TLS' and 'Self-Remediation', enhancing user guidance on these features. - Removed outdated files related to 'Device Identity', 'Load Balancing', and 'Single Sign-out', streamlining the documentation. - Updated existing files to reflect new titles and keywords, improving searchability and relevance. - Enhanced routing documentation to clarify proxying and load balancing methods, ensuring users have comprehensive resources. This commit improves the organization, clarity, and usability of the documentation, providing users with up-to-date and accessible information on Pomerium's capabilities.
… identity management - Updated sidebar entries for improved organization and clarity, including the addition of new categories for 'Self-Managed (Core)' and 'Cloud Managed (Zero)'. - Introduced new documentation files covering advanced policies, routes, and user identity verification, enhancing user guidance on these features. - Removed outdated files related to 'Getting Users Identity' and 'JWT Verification', streamlining the documentation. - Updated existing files to reflect new titles and keywords, improving searchability and relevance. - Added new images and examples to clarify complex concepts and processes. This commit improves the structure, clarity, and usability of the documentation, providing users with up-to-date and accessible information on Pomerium's capabilities and identity management features.
…erences and Docker image paths - Updated links to the Self-Hosted Authenticate Service across multiple files to point to the new authentication documentation. - Changed all instances of the Pomerium Docker image from 'cr.pomerium.com' to 'pomerium.com' for consistency and clarity. - Enhanced various documentation sections to improve user guidance on authentication and deployment processes. This commit improves the accuracy and usability of the documentation, ensuring users have access to the latest information regarding Pomerium's authentication services and deployment practices.
- Introduced new documentation files for Pomerium Core, detailing installation methods, configuration, and running the server using pre-built binaries, Docker images, or building from source. - Added an extensive upgrading guide for both Pomerium Core and Enterprise, outlining breaking changes, deprecations, and important notes for each version. - Removed outdated files related to Pomerium Zero and consolidated relevant content into the new structure, enhancing clarity and usability. - Updated various sections to improve user guidance on installation, configuration, and upgrade processes. This commit enhances the documentation's organization and accessibility, ensuring users have up-to-date and comprehensive resources for deploying and managing Pomerium.
…y updates - Added new features including a feedback widget, improved IdP directory sync performance, and a new "Exists" condition for external data sources. - Expanded `--disable-validation` into a new `--validation-mode` option with additional modes. - Fixed several UI issues in the policy builder and restricted access to the debug "DataBroker Browser" page to global admins. - Included various bug fixes across multiple versions, ensuring a smoother user experience and improved functionality. This commit provides users with comprehensive information on the latest changes and improvements in the upgrading process for Pomerium.
- Updated the title of the upgrading documentation to 'Upgrading' for brevity. - Enhanced the description to include 'changelog' for better context on the content provided. - These changes aim to improve the clarity and accessibility of the upgrading process for both Pomerium Core and Enterprise users.
- Introduced comprehensive documentation on Clusters in Pomerium Zero, detailing architecture, deployment, and management. - Added new images to illustrate cluster concepts and configurations. - Updated the upgrading documentation to reflect recent changes, including the removal of deprecated files and integration of relevant content. - Enhanced troubleshooting sections for cluster status alerts, providing clear resolution steps for common issues. These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to up-to-date resources for managing Pomerium Zero and its clusters.
- Modified the pre-commit configuration to exclude a specific Kubernetes reference file. - Updated Docusaurus configuration to include a webpack fix for debugging. - Upgraded Docusaurus dependencies to the latest version. - Enhanced documentation by adding a new section for custom domains in Pomerium Zero, including detailed instructions and images. - Revised various documentation links to ensure consistency and accuracy, particularly for Kubernetes deployment references. - Removed outdated CORS documentation and integrated relevant content into troubleshooting guides. - Added a comprehensive troubleshooting guide to assist users with common configuration issues. These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to up-to-date resources for managing Pomerium and its deployment processes.
- Commented out the custom plugin for webpack debugging in `docusaurus.config.js` to streamline configuration. - Upgraded `mermaid` from version 10.9.3 to 11.4.1 and `redocusaurus` from 2.0.2 to 2.2.0 in `package.json` for improved functionality. - Added `image-size` as a new dependency in `devDependencies` and updated `prettier` to version 3.4.2. - Removed the `webpackDebugFix.js` file to eliminate redundant code. These changes enhance the clarity of the configuration and ensure the project uses the latest dependencies for better performance and maintainability.
…ntegrations - Introduced new documentation files for various identity providers including Apple, Auth0, Azure, Cognito, GitHub, GitLab, Google, Okta, OneLogin, and Ping, enhancing user guidance on integration processes. - Updated sidebar entries for improved organization and clarity, adding new categories for 'User Identity' and 'User Standing'. - Added comprehensive documentation on device context and request context integrations, detailing their functionalities and configurations. - Removed outdated files and consolidated relevant content to streamline the documentation. - Enhanced existing documentation with new images and examples to clarify complex concepts and processes. These changes improve the structure, clarity, and usability of the documentation, ensuring users have access to up-to-date resources for managing user identity and integrations with Pomerium.
- Removed outdated version links from the Docusaurus configuration to streamline navigation. - Cleaned up sidebar entries by commenting out deprecated categories and consolidating relevant documentation, enhancing clarity and organization. - Updated import paths in the configuration documentation for consistency. - Improved table formatting in service URLs documentation for better readability. These changes enhance the overall usability and clarity of the documentation, ensuring users have access to the most relevant and organized resources for Pomerium.
- Refactored `docusaurus.config.js` to use updated imports for code themes, enhancing maintainability. - Upgraded several MUI packages and `prism-react-renderer` in `package.json` to their latest versions for improved functionality and performance. - Corrected documentation links related to device identity across multiple files, ensuring users are directed to the correct resources. - Updated redirect paths in `_redirects` to reflect the new documentation structure for device identity. These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to the most relevant and up-to-date resources for Pomerium.
- Updated the sidebar link for the Integrations category to point to the new documentation structure. - Added comprehensive new documentation files for integrating external data sources and configuring identity providers, including Keycloak. - Introduced detailed guides on using external data sources with Pomerium, including supported formats and configuration settings. - Removed outdated OIDC documentation and consolidated relevant content to streamline user guidance. - Added images and examples to clarify integration processes and enhance user understanding. These changes improve the clarity, organization, and usability of the documentation, ensuring users have access to up-to-date resources for managing integrations with Pomerium.
- Standardized formatting of titles and descriptions in the Keycloak integration guide. - Consolidated image display for better visual flow and readability. - Removed unnecessary blank lines to enhance document cleanliness. - Updated the caution note formatting for improved emphasis. These changes improve the overall clarity and usability of the Keycloak integration documentation, ensuring users have a more streamlined experience when configuring Pomerium with Keycloak.
- Removed unnecessary comments and links in the sidebars to streamline navigation. - Standardized formatting across multiple files, ensuring consistent use of apostrophes and punctuation. - Enhanced descriptions and titles for better clarity in various guides, including those related to authentication, authorization, and device identity. - Consolidated and improved the organization of documentation related to Pomerium's capabilities and integrations. These changes enhance the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
- Updated sidebar links to correct paths, ensuring accurate navigation to Kubernetes deployment references. - Standardized formatting across multiple files, including titles and descriptions, for improved readability. - Enhanced documentation by correcting typos and ensuring consistent terminology, particularly in the context of device identity and Kubernetes configurations. - Consolidated and improved the organization of documentation related to Pomerium's capabilities and integrations, including the introduction of new sections for WebAuthn device identity. These changes enhance the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
- Removed the 'APIs' dropdown from the sidebar in `docusaurus.config.js` to streamline navigation. - Enhanced the description of Pomerium in `index.mdx` to clarify its functionality, emphasizing the verification of user identity, device state, and request context. - Improved formatting and clarity in the documentation, ensuring consistent terminology and readability. These changes enhance the overall usability and clarity of the documentation, providing users with a more coherent resource for understanding Pomerium's capabilities.
- Updated links across multiple files to ensure accurate navigation to identity provider and integration resources. - Corrected paths for various documentation sections, including device identity and authentication, to reflect the new structure. - Enhanced descriptions and formatting for improved readability and coherence in guides related to user identity management and integrations. - Consolidated and organized documentation to streamline user guidance on Pomerium's capabilities and integrations. These changes improve the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
- Updated multiple links across various files to ensure accurate navigation to the correct documentation sections, particularly for identity providers and integration resources. - Corrected paths for guides related to device identity, authentication, and troubleshooting to reflect the new structure. - Enhanced descriptions and formatting for improved readability and coherence in guides, including those related to user identity management and integrations. - Consolidated and organized documentation to streamline user guidance on Pomerium's capabilities and integrations. These changes enhance the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Generally, I'm a fan. I didn't review every line, but the new structure is an improvement over the current. |
…x.mdx to improve clarity of capabilities.
- Added numerous new redirects for renamed documentation pages to improve navigation and accessibility. - Consolidated and updated paths for various guides, including recovery token generation, mkcert installation, and integrations. - Enhanced organization of documentation by restructuring paths for capabilities, integrations, and management guides. These changes streamline user access to updated resources and improve the overall clarity of the documentation structure.
- Changed links in the connection.mdx file to point to the correct deployment documentation for Pomerium CLI and Desktop App. - Updated links in the codec-type.mdx file to reflect the new paths for Kubernetes parameters and global configuration. These changes enhance the accuracy and accessibility of the documentation for users.
|
The backport to To backport manually, run these commands in your terminal: # Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-0-28-0 0-28-0
# Navigate to the new working tree
cd .worktrees/backport-0-28-0
# Create a new branch
git switch --create backport-1726-to-0-28-0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick --mainline 1 12e2cddb0289bb4c14696031505af7fde4eafd57
# Push it to GitHub
git push --set-upstream origin backport-1726-to-0-28-0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-0-28-0Then, create a pull request where the |
desimone
added a commit
that referenced
this pull request
Jan 20, 2025
This pull request consolidates a large set of changes to Pomerium’s documentation. It refines organization, updates integrations, removes outdated content, and simplifies navigation. - **New Integration Guides** - Added guides for Apple, Auth0, Azure, Cognito, GitHub, GitLab, Google, OIDC, Okta, OneLogin, Ping, and Keycloak - Included images, examples, and troubleshooting steps - **Documentation Structure Overhaul** - Consolidated categories (e.g., "Pomerium Zero," "Pomerium Core," "Community") into a streamlined sidebar - Removed outdated guidelines (Code of Conduct, Contributing) and deprecated sections - Merged cryptography details into the Security Policy page - **Deployment and Kubernetes Updates** - Introduced new “Deploy” category, consolidating references for Kubernetes, enterprise, and device identity - Added quick start references, cluster management guides, and new examples - Updated Docker image references to `latest` tag for clarity and consistency - **Enterprise Guides and Enhanced Features** - Created detailed docs for Pomerium Enterprise: installation, configuration, metrics, and clusters - Expanded device context, request context, and advanced policy documentation - Improved upgrading guides for both Pomerium Core and Enterprise - **Security & Authentication Improvements** - Integrated cryptography docs into a single security-focused resource - Removed the standalone “Hosted Authenticate Service” section in favor of a unified authentication guide - Clarified JWT usage, identity verification, and zero trust concepts - **Refinements and Cleanup** - Fixed or removed broken links, consolidated multiple references, and standardized paths - Upgraded Docusaurus and other dependencies (e.g., mermaid, redocusaurus, cspell, Prettier) for better performance - Improved sidebars, table formatting, and visual flow in key docs - Updated pre-commit workflows to ensure consistent formatting and spelling checks These updates greatly improve the clarity, consistency, and user-friendliness of the Pomerium documentation.
desimone
added a commit
that referenced
this pull request
Jan 20, 2025
* docs: restructure, clarify, consolidate existing docs (#1726) This pull request consolidates a large set of changes to Pomerium’s documentation. It refines organization, updates integrations, removes outdated content, and simplifies navigation. - **New Integration Guides** - Added guides for Apple, Auth0, Azure, Cognito, GitHub, GitLab, Google, OIDC, Okta, OneLogin, Ping, and Keycloak - Included images, examples, and troubleshooting steps - **Documentation Structure Overhaul** - Consolidated categories (e.g., "Pomerium Zero," "Pomerium Core," "Community") into a streamlined sidebar - Removed outdated guidelines (Code of Conduct, Contributing) and deprecated sections - Merged cryptography details into the Security Policy page - **Deployment and Kubernetes Updates** - Introduced new “Deploy” category, consolidating references for Kubernetes, enterprise, and device identity - Added quick start references, cluster management guides, and new examples - Updated Docker image references to `latest` tag for clarity and consistency - **Enterprise Guides and Enhanced Features** - Created detailed docs for Pomerium Enterprise: installation, configuration, metrics, and clusters - Expanded device context, request context, and advanced policy documentation - Improved upgrading guides for both Pomerium Core and Enterprise - **Security & Authentication Improvements** - Integrated cryptography docs into a single security-focused resource - Removed the standalone “Hosted Authenticate Service” section in favor of a unified authentication guide - Clarified JWT usage, identity verification, and zero trust concepts - **Refinements and Cleanup** - Fixed or removed broken links, consolidated multiple references, and standardized paths - Upgraded Docusaurus and other dependencies (e.g., mermaid, redocusaurus, cspell, Prettier) for better performance - Improved sidebars, table formatting, and visual flow in key docs - Updated pre-commit workflows to ensure consistent formatting and spelling checks These updates greatly improve the clarity, consistency, and user-friendliness of the Pomerium documentation. * fix link
This was referenced Jan 20, 2025
desimone
added a commit
that referenced
this pull request
Jan 23, 2025
…zed docs (#1755) - Added redirects for old capabilities pages (hosted-authenticate-service, mtls-clients, etc.). - Updated Helm references to point to /docs/deploy/k8s/install. - Removed outdated references (pre 0.20) and consolidated rules to avoid 404s. - Grouped rules logically by doc category for easier maintenance. Follow-up to [#1726](#1726)
backport-actions-token bot
pushed a commit
that referenced
this pull request
Jan 23, 2025
…zed docs (#1755) - Added redirects for old capabilities pages (hosted-authenticate-service, mtls-clients, etc.). - Updated Helm references to point to /docs/deploy/k8s/install. - Removed outdated references (pre 0.20) and consolidated rules to avoid 404s. - Grouped rules logically by doc category for easier maintenance. Follow-up to [#1726](#1726)
desimone
added a commit
that referenced
this pull request
Jan 23, 2025
…zed docs (#1756) chore: update _redirects to match new sitemap (27 vs 28) and reorganized docs (#1755) - Added redirects for old capabilities pages (hosted-authenticate-service, mtls-clients, etc.). - Updated Helm references to point to /docs/deploy/k8s/install. - Removed outdated references (pre 0.20) and consolidated rules to avoid 404s. - Grouped rules logically by doc category for easier maintenance. Follow-up to [#1726](#1726) Co-authored-by: bobby <[email protected]>
6 tasks
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.
Summary
This PR reorganizes our documentation to unify repetitive content (e.g., multiple versions of identity/JWT verification, CLI usage, and certificate guides) into a more readable structure. We want newcomers to see a clear “start here” path, discover high-level product capabilities, and then explore advanced references once they’re ready for production. No changes have been made to our existing reference docs or guides.
Improved Onboarding Flow
Consolidated Overlapping Docs (many others)
Docs Platform Improvements
docusaurus.config.jsfor future use.Follow-Up Work
Request for Review