MyST Markdown Refactor #7
Open
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
We have README.md
Support pixi run build as a default that works without a LaTeX distribution.
Fewer, common targets for `build`. Rename build-paper to build-pdf and only include the PDF build targets.
Update CMakeLists.txt. Update manuscript tasks and their names.
These have now been replaced.
Verify the submitted article bundle can be reproduced.
Fixed in upstream mystmd 1.6.1.
Update and fix versions of the actions used and runners. Replace build-complete with build-meca and other pixi tasks. The MECA build target now targets the reproducible MECA zip with built PDFs, JATS XML, source code and data.
jhlegarreta
reviewed
Sep 25, 2025
|
@jhlegarreta thanks for the review!
Yes, in future iterations we should integrate a version of this into the ITKModuleTemplate. This is intended as a starting point for a submission that does not necessarily extend or rely on ITK even though it is used in a sample. |
jhlegarreta
approved these changes
Sep 26, 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.
This pull request updates the Insight Journal Article Template to adopt MyST Markdown as the primary authoring format, implements reproducible dependency management with Pixi, adds support for MECA output for standardized journal submission, and introduces integrated source code testing and validation workflows.
Transition to MyST Markdown
The template now leverages MyST Markdown for manuscript drafting—enabling rich scientific writing with support for figures, equations, citations, and cross-references. MyST bridges the simplicity of Markdown with features needed for scholarly publishing, supporting outputs in HTML, PDF, DOCX, and LaTeX formats without sacrificing authoring flexibility.
Advantages of MyST Markdown
Reproducible Dependency Management with Pixi
Dependency management and build automation now use Pixi. Pixi environments ensure that all contributors share the same set of tools and libraries, supporting completely reproducible builds—from manuscript generation to source code compilation and testing.
Key benefits:
Standardized MECA Output
The build system adds direct support for producing MECA (Manuscript Exchange Common Approach) archives—a standardized packaging format recognized by scientific journals. MECA output includes all necessary manuscript content, figures, code, and supporting data, streamlining the submission process.
Integrated Source Code Testing and Validation
The template contains a dedicated workflow for managing and testing source code (e.g., ITK-based C++ examples) alongside the manuscript. Features include:
This overhaul empowers scientific authors to rapidly create, test, and submit Insight Journal manuscripts with robust reproducibility and modern open science standards.