Skip to content

docs: restructure dev container documentation #21157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
mafredri merged 2 commits into from
Dec 9, 2025
Merged

docs: restructure dev container documentation #21157

mafredri merged 2 commits into from
Dec 9, 2025

Conversation

@mafredri
Copy link
Member

@mafredri mafredri commented Dec 8, 2025 •
edited
Loading

Dev container admin docs were scattered across two locations: the Docker-based
integration under extending-templates/ and Envbuilder under managing-templates/.
There was no landing page explaining that two approaches exist or helping admins
choose between them.

This moves everything under admin/integrations/devcontainers/ with a decision
guide at the top. Dev containers are an integration with the dev container
specification, so integrations/ is a natural fit alongside JFrog, Vault, etc.

Stub pages remain at the original locations for discoverability.

New structure:

admin/integrations/devcontainers/
├── index.md                                # Landing page + decision guide
├── integration.md                          # Docker-based dev containers
└── envbuilder/
    ├── index.md
    ├── add-envbuilder.md
    ├── envbuilder-security-caching.md
    └── envbuilder-releases-known-issues.md

Refs #21080

@mafredri mafredri force-pushed the mafredri/restructure-devcontainer-docs branch 5 times, most recently from e7dac02 to 0ebab5c Compare December 8, 2025 11:20
@mafredri mafredri marked this pull request as ready for review December 8, 2025 11:20
@mafredri mafredri added the doc-check Assign this label to PRs to check for any doc changes. label Dec 8, 2025
@github-actions
Copy link

github-actions bot commented Dec 8, 2025

Task created: https://dev.coder.com/tasks/mafredri/fc032bf5-93a2-4ec3-9d20-a28d77179089

@mafredri Coder
Copy link
Member Author

mafredri commented Dec 8, 2025

📚 Documentation Check

✨ No Changes Needed

Reason: This PR is a documentation-only restructure that successfully reorganizes dev containers documentation. All documentation has been properly updated in this PR.

What was done:

  • Moved dev containers docs from admin/templates/ to new admin/integrations/devcontainers/ section
  • Created new landing page explaining both approaches (Dev Containers Integration vs Envbuilder)
  • Added comprehensive 266-line guide for the Dev Containers Integration
  • Created proper stub pages that redirect to the main integration documentation
  • Updated all internal cross-references
  • Added proper redirects in _redirects for backwards compatibility
  • Updated manifest.json with the new documentation structure

The restructure improves discoverability by consolidating both dev containers approaches under a dedicated integrations section, with clear guidance on when to use each approach.

This comment was generated by an AI Agent through Coder Tasks

@mafredri mafredri force-pushed the mafredri/restructure-devcontainer-docs branch 4 times, most recently from 85609ac to e51d282 Compare December 8, 2025 14:23
@mafredri
docs: restructure dev container documentation
9fae08a 
Dev container admin docs were scattered across two locations: the Docker-based
integration under extending-templates/ and Envbuilder under managing-templates/.
There was no landing page explaining that two approaches exist or helping admins
choose between them.

This moves everything under admin/integrations/devcontainers/ with a decision
guide at the top. Dev containers are an integration with the dev container
specification, so integrations/ is a natural fit alongside JFrog, Vault, etc.

Stub pages remain at the original locations for discoverability.

New structure:

  admin/integrations/devcontainers/
  ├── index.md                                # Landing page + decision guide
  ├── integration.md                          # Docker-based dev containers
  └── envbuilder/
      ├── index.md
      ├── add-envbuilder.md
      ├── envbuilder-security-caching.md
      └── envbuilder-releases-known-issues.md

Refs #21080
@mafredri mafredri force-pushed the mafredri/restructure-devcontainer-docs branch from e51d282 to 9fae08a Compare December 8, 2025 14:24
david-fraley
david-fraley previously requested changes Dec 8, 2025
View reviewed changes
Copy link
Collaborator

@david-fraley david-fraley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

High level looks good. Can you head to the preview links, and make sure all the pages render A-OK including the various page links and !notes you have?

Also, consider adding in some pics to show what Devcontainers actually looks like when setup and running in the UI!

DanielleMaywood
DanielleMaywood approved these changes Dec 9, 2025
View reviewed changes
Copy link
Contributor

@DanielleMaywood DanielleMaywood left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given this is just a little restructuring I'm happy with approving this. We can resolve any issues with the existing documentation in a follow-up PR

@mafredri
Copy link
Member Author

mafredri commented Dec 9, 2025 •
edited
Loading

Can you head to the preview links, and make sure all the pages render A-OK including the various page links and !notes you have?

@david-fraley What does "preview links" refer to? If we have a way to view docs from PR I'm happy to take a look, but I'm not aware of it.

There aren't a whole lot of !NOTE additions as this is mostly a restructuring PR of existing content. All the links are already validated by a linter.

@mafredri mafredri dismissed david-fraley’s stale review December 9, 2025 11:01

Let's plan some follow-up changes and keep this PR scoped to restructuring.

@mafredri mafredri merged commit 97bc7eb into main Dec 9, 2025
30 checks passed
@mafredri mafredri deleted the mafredri/restructure-devcontainer-docs branch December 9, 2025 11:03
@github-actions github-actions bot locked and limited conversation to collaborators Dec 9, 2025
@david-fraley
Copy link
Collaborator

david-fraley commented Dec 9, 2025

Can you head to the preview links, and make sure all the pages render A-OK including the various page links and !notes you have?

@david-fraley What does "preview links" refer to? If we have a way to view docs from PR I'm happy to take a look, but I'm not aware of it.

There aren't a whole lot of !NOTE additions as this is mostly a restructuring PR of existing content. All the links are already validated by a linter.

@mafredri basically me being nervous of another 404 situation. We should be fine

@mafredri
Copy link
Member Author

mafredri commented Dec 9, 2025

@mafredri basically me being nervous of another 404 situation. We should be fine

@david-fraley Gotcha. Full disclosure I took a risk in coder/coder.com#524 and updated the redirects directly without creating yet another set of redirects, so if someone bookmarked certain Envbuilder docs between Saturday and today, they'll get 404's. 😔 I chose simplicity over covering this minimal edge-case.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@david-fraley david-fraley david-fraley left review comments

@DanielleMaywood DanielleMaywood DanielleMaywood approved these changes

Assignees

@mafredri mafredri

Labels

doc-check Assign this label to PRs to check for any doc changes.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@mafredri @david-fraley @DanielleMaywood