[WIP] Migrate syntax guide and contribution pages from docs-builder #3735
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
Copy syntax guide documentation from docs-builder repository to contribute-docs/syntax/. Includes 37 markdown files covering MyST syntax, directives, and custom Elastic documentation features. Changes from original: - Add legacy documentation section linking to AsciiDoc guide - Fix reference from "See" to "refer to"
Copy contribution documentation from docs-builder to contribute-docs/contribute/. Includes guides for local and web-based contribution, how-to guides for moving files and redirects, and comprehensive cumulative documentation guidance. Changes from original: - Update absolute paths to relative paths for new location - Add link to documentation tools in locally.md prerequisites - Simplify on-the-web.md and add detailed GitHub editing steps - Add legacy docs reference in on-the-web.md - Fix cumulative docs link path in locally.md - Update "See" to "refer to" throughout - Remove branching strategy references (not migrated) - Remove development section reference (not migrated) - Update navigation title for contribute index - Clean up local preview section wording
Create new tools.md page documenting helpful authoring tools including the Elastic Docs VS Code extension. Includes animated demo and installation instructions. Features: - VS Code extension description with key capabilities - Availability in desktop and web editors (Codespaces, github.dev) - Links to VS Code Marketplace and GitHub - Screenshot showing extension in action
Create dedicated page for contributing to elastic.co/guide (legacy AsciiDoc documentation). Consolidates legacy docs contribution information from contribute index and on-the-web pages. Includes: - Overview of legacy documentation system and covered versions - Web-based contribution workflow - Local contribution guidance - Cross-system update workflow using pandoc
Create index page for how-to section organizing practical guides for common documentation tasks including moving files, setting up redirects, and writing cumulative documentation.
Update main landing page to link to newly migrated content: - Link to local syntax guide instead of external docs-builder - Link to local contribution guide instead of external docs-builder - Link to local legacy docs guide instead of external docs-builder Provides clear entry points for all documentation systems.
Add syntax guide and contribution guides sections to toc.yml. Organizes migrated content into logical hierarchy: - Syntax guide with 37 markdown files - Contribution guides organized by workflow (local, web, legacy) - Documentation tools page - How-to guides subsection with cumulative docs, file moves, and redirects
Change tools.mdd# to tools.md#vs-code-extension
- Copy shared _snippets folder from docs-builder - Fix absolute paths (/syntax/, /contribute/) to relative paths - Fix snippet includes to use correct relative paths - Remove broken link to configure/content-set, link to external docs-builder instead - Update configure/site reference to external docs-builder guide These changes resolve path errors from moving content into contribute-docs.
- Use absolute paths (/contribute-docs/) for all cross-references - Fix malformed relative paths (../syntax../, ../../.., etc) - Escape substitution variables in example table with backticks All 24 errors now resolved.
- Fix snippet includes in csv-include.md and reference.md to use absolute paths - Fix malformed ../../../contribute-docs path to /contribute-docs - Fix snippet reference to cumulative docs from syntax folder Attempt to resolve remaining path errors.
Adds the tag-processing.md snippet file that was missing from the _snippets folder. This file is referenced in cumulative-docs/index.md and is needed for proper documentation rendering.
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.
https://github.com/elastic/docs-content-internal/issues/338
Note
This has two components:
(a) lift-and-shift
(b) some edited content + net-new pages
Therefore, it probably makes sense for reviewers to only suggest edits for (b) unless they find something unacceptable on the untouched pages.
An independent audit and editing phase for all these pages will follow once this PR merges.
URL preview
https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/3735/contribute-docs/
Summary of Commits
Expand for more details
Summary of Changes
🚚 Content ported
Expand for more details
Syntax guide (37 files)
docs-builder/docs/syntax/copied tocontribute-docs/syntax/without modificationsContribution guides
contribute/locally.md- Local contribution setup and workflowcontribute/on-the-web.md- Web-based contribution workflowcontribute/how-to/move.md- Moving files and folders guidecontribute/how-to/redirects.md- Setting up redirects guidecontribute/how-to/cumulative-docs/(5 files) - Cumulative documentation guides✍🏿 Content edited during migration
Expand for more details
contribute-docs/index.md
contribute-docs/contribute/locally.md
contribute-docs/contribute/on-the-web.md
contribute-docs/contribute/index.md
contribute-docs/syntax/index.md
👩🏻🍼 Net new pages
Expand for more details
contribute-docs/contribute/tools.md
contribute-docs/contribute/legacy-docs.md
contribute-docs/contribute/how-to/index.md
Navigation changes
Expand for more details
contribute-docs/toc.yml