added versioning to syllabus and added Release 1.0.1 to the versioned docs#92
added versioning to syllabus and added Release 1.0.1 to the versioned docs#92
Conversation
… docs Signed-off-by: René <snooz@posteo.de>
|
🚀 Preview deployed to https://robotframework-RFCP-syllabus-pr-92.surge.sh/robotframework-RFCP-syllabus/ |
Signed-off-by: René <snooz@posteo.de>
There was a problem hiding this comment.
Pull request overview
Adds Docusaurus docs versioning for the syllabus so that preview builds include the current “next” docs while production builds publish only released versions, and introduces the first released docs snapshot (1.0.1).
Changes:
- Added
1.0.1as the first versioned docs release (versions list, versioned sidebars, and versioned docs content). - Introduced preview vs production build modes via
DOCS_BUILD_MODE, plus corresponding npm scripts and CI workflow updates. - Adjusted the remark code-block line-length check to skip
versioned_docssnapshots and added a docs version dropdown in the navbar.
Reviewed changes
Copilot reviewed 47 out of 48 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| website/versions.json | Declares released docs versions (adds 1.0.1). |
| website/versioned_sidebars/version-1.0.1-sidebars.json | Sidebar definition for the 1.0.1 docs snapshot. |
| website/versioned_docs/version-1.0.1/overview.md | Versioned docs snapshot content: overview. |
| website/versioned_docs/version-1.0.1/learning_objectives.md | Versioned docs snapshot content: learning objectives list. |
| website/versioned_docs/version-1.0.1/glossary/category.json | Versioned docs snapshot: glossary category metadata. |
| website/versioned_docs/version-1.0.1/glossary/Glossary.md | Versioned docs snapshot: glossary content. |
| website/versioned_docs/version-1.0.1/example-exam/category.json | Versioned docs snapshot: example exam category metadata. |
| website/versioned_docs/version-1.0.1/example-exam/Example-exam.mdx | Versioned docs snapshot: example exam page content. |
| website/versioned_docs/version-1.0.1/chapter-05/category.json | Versioned docs snapshot: chapter 5 category metadata. |
| website/versioned_docs/version-1.0.1/chapter-05/02_control_structures.md | Versioned docs snapshot: chapter 5.2 content. |
| website/versioned_docs/version-1.0.1/chapter-05/01_advanced_variables.md | Versioned docs snapshot: chapter 5.1 content. |
| website/versioned_docs/version-1.0.1/chapter-05/00_overview.md | Versioned docs snapshot: chapter 5 overview. |
| website/versioned_docs/version-1.0.1/chapter-04/category.json | Versioned docs snapshot: chapter 4 category metadata. |
| website/versioned_docs/version-1.0.1/chapter-04/05_skip.md | Versioned docs snapshot: chapter 4.5 content. |
| website/versioned_docs/version-1.0.1/chapter-04/04_tags.md | Versioned docs snapshot: chapter 4.4 content. |
| website/versioned_docs/version-1.0.1/chapter-04/03_init_files.md | Versioned docs snapshot: chapter 4.3 content. |
| website/versioned_docs/version-1.0.1/chapter-04/02_teardowns.md | Versioned docs snapshot: chapter 4.2 content. |
| website/versioned_docs/version-1.0.1/chapter-04/01_setups.md | Versioned docs snapshot: chapter 4.1 content. |
| website/versioned_docs/version-1.0.1/chapter-04/00_overview.md | Versioned docs snapshot: chapter 4 overview. |
| website/versioned_docs/version-1.0.1/chapter-03/category.json | Versioned docs snapshot: chapter 3 category metadata. |
| website/versioned_docs/version-1.0.1/chapter-03/05_advanced_importing.md | Versioned docs snapshot: chapter 3.5 content. |
| website/versioned_docs/version-1.0.1/chapter-03/04_datadriven.md | Versioned docs snapshot: chapter 3.4 content. |
| website/versioned_docs/version-1.0.1/chapter-03/03_user_keyword.md | Versioned docs snapshot: chapter 3.3 content. |
| website/versioned_docs/version-1.0.1/chapter-03/02_variables.md | Versioned docs snapshot: chapter 3.2 content. |
| website/versioned_docs/version-1.0.1/chapter-03/01_resource_file.md | Versioned docs snapshot: chapter 3.1 content. |
| website/versioned_docs/version-1.0.1/chapter-03/00_overview.md | Versioned docs snapshot: chapter 3 overview. |
| website/versioned_docs/version-1.0.1/chapter-02/category.json | Versioned docs snapshot: chapter 2 category metadata. |
| website/versioned_docs/version-1.0.1/chapter-02/06_writing_test.md | Versioned docs snapshot: chapter 2.6 content. |
| website/versioned_docs/version-1.0.1/chapter-02/05_keyword_interface.md | Versioned docs snapshot: chapter 2.5 content. |
| website/versioned_docs/version-1.0.1/chapter-02/04_keyword_imports.md | Versioned docs snapshot: chapter 2.4 content. |
| website/versioned_docs/version-1.0.1/chapter-02/03_executing.md | Versioned docs snapshot: chapter 2.3 content. |
| website/versioned_docs/version-1.0.1/chapter-02/02_suitefile_syntax.md | Versioned docs snapshot: chapter 2.2 content. |
| website/versioned_docs/version-1.0.1/chapter-02/01_suitefile.md | Versioned docs snapshot: chapter 2.1 content. |
| website/versioned_docs/version-1.0.1/chapter-02/00_overview.md | Versioned docs snapshot: chapter 2 overview. |
| website/versioned_docs/version-1.0.1/chapter-01/category.json | Versioned docs snapshot: chapter 1 category metadata. |
| website/versioned_docs/version-1.0.1/chapter-01/05_organization.md | Versioned docs snapshot: chapter 1.5 content. |
| website/versioned_docs/version-1.0.1/chapter-01/04_styles.md | Versioned docs snapshot: chapter 1.4 content. |
| website/versioned_docs/version-1.0.1/chapter-01/03_syntax.md | Versioned docs snapshot: chapter 1.3 content. |
| website/versioned_docs/version-1.0.1/chapter-01/02_architecture.md | Versioned docs snapshot: chapter 1.2 content. |
| website/versioned_docs/version-1.0.1/chapter-01/01_purpose.md | Versioned docs snapshot: chapter 1.1 content. |
| website/versioned_docs/version-1.0.1/chapter-01/00_overview.md | Versioned docs snapshot: chapter 1 overview. |
| website/src/remark/remark-code-max-line-length.js | Skips max-line-length failures for versioned docs snapshots. |
| website/package.json | Adds build:preview / build:production scripts. |
| website/docusaurus.config.ts | Adds DOCS_BUILD_MODE handling, includeCurrentVersion, and version dropdown. |
| website/README.md | Documents the new build modes. |
| .github/workflows/release-pages.yml | Uses production build mode for releases. |
| .github/workflows/pr-preview-surge.yml | Uses preview build mode for PR previews. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
🚀 Preview deployed to https://robotframework-RFCP-syllabus-pr-92.surge.sh/robotframework-RFCP-syllabus/ |
|
🚀 Preview deployed to https://robotframework-RFCP-syllabus-pr-92.surge.sh/robotframework-RFCP-syllabus/ |
Signed-off-by: René <snooz@posteo.de>
|
🚀 Preview deployed to https://robotframework-RFCP-syllabus-pr-92.surge.sh/robotframework-RFCP-syllabus/ |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 47 out of 48 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| RELEASE_TAG="${{ github.event.release.tag_name }}" | ||
| DOCS_DIR="website/versioned_docs/${RELEASE_TAG}" | ||
|
|
||
| if [[ ! -d "${DOCS_DIR}" ]]; then | ||
| echo "::error::Missing docs snapshot for release tag '${RELEASE_TAG}'." | ||
| echo "Expected directory: ${DOCS_DIR}" | ||
| echo "Available directories in website/versioned_docs:" | ||
| ls -1 website/versioned_docs || true | ||
| exit 1 | ||
| fi |
There was a problem hiding this comment.
The release workflow is checking for a docs snapshot at website/versioned_docs/${RELEASE_TAG}, but Docusaurus stores versioned snapshots under website/versioned_docs/version-<version> (e.g. version-1.0.1). As written, the job will fail for a 1.0.1 tag even though the snapshot exists. Update the check to look for website/versioned_docs/version-${RELEASE_TAG} (and consider normalizing tags like v1.0.1 if that’s a possibility).
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
Fixed in commit 85d629a. The check now looks for website/versioned_docs/version-${VERSION} and also strips a leading v from the tag name (so both 1.0.1 and v1.0.1 tags correctly match version-1.0.1).
|
I noticed we currently show the version in two places: once in the navbar and once above the page content. My suggestion would be to remove the page-level version indicator and keep the navbar version as the primary source of truth. If extra clarity is needed, we could prefix the navbar value with “Version:” or simply “v”, though the current placement may already be clear enough. If the page-level indicator is required for responsive or accessibility reasons, could we move it to the right side of the content header area? That would prevent it from visually interfering with the syllabus page titles. 
|
|
Another thing I noticed: when navigating via the top navbar, the selected version resets. This does not happen when navigating through the sidebar navigation, where the selected version is preserved. I would expect both navigation methods to behave consistently, ideally by keeping the currently selected version when moving between pages. |
|
Small UX issue with the version selector: the menu opens on hover, but clicking the version that is already active triggers a page reload and resets the current anchor/scroll position. Expected behavior: clicking the active version should either do nothing or simply close the menu, rather than navigating to the same page again. The 'change' would only be activated when clicking on a different version in the menu that opens up on mouse-over. 
|
…dge, use doc-type navbar items Agent-Logs-Url: https://github.com/robotframework/robotframework-RFCP-syllabus/sessions/d026ff9e-b0e5-4e58-9969-750936ad6311 Co-authored-by: Snooz82 <41592183+Snooz82@users.noreply.github.com>
|
@GerwinLaagland i just used the Docusaurus feature for versioning docs. the version picker and the indicators are all standard. we can improve it in the future, but such changes are irrelevant for syllabus versioning and can be done at any point after the release. |
Done in commit
Fixed in commit
This is a built-in Docusaurus limitation for the |
|
I thought to at least mention the list of things that I noticed. I suspected you did some hybrid vibecoding / using docusaurus. I never know how the cook prepares these things. 😄 I'm not sure where the co-pilot comes up with some of these statements, given that nothing further has changed to my knowledge. But for now looks good to me otherwise. I can raise items for this in the future if you want for the things you agree on. For now you can have my stamp of approval. |
Previews will include a version called
nextwhich is the current working head.Production Builds will only contain versioned version.
Adds Docusaurus docs versioning for the syllabus so that preview builds include the current “next” docs while production builds publish only released versions, and introduces the first released docs snapshot (1.0.1).
Changes:
1.0.1as the first versioned docs release (versions list, versioned sidebars, and versioned docs content).DOCS_BUILD_MODE, plus corresponding npm scripts and CI workflow updates.versioned_docssnapshots and added a docs version dropdown in the navbar.