Skip to content

Add parseorg module#143

Merged
joerdav merged 9 commits into
joerdav:mainfrom
ryanprior:org-parser
Oct 27, 2025
Merged

Add parseorg module#143
joerdav merged 9 commits into
joerdav:mainfrom
ryanprior:org-parser

Conversation

@ryanprior

@ryanprior ryanprior commented Jul 6, 2025

Copy link
Copy Markdown
Contributor

Hi there! Here's an org-parser in pursuit of #66.

Why?

In order to support org-mode with minimal refactoring, I decided to copy the Markdown parser & make minimal changes to it to make it work. I also copied the test suite and made minimal changes there.

What does this PR contain?

  • a package that parses tasks in org-mode documentation (parseorg), following the pattern from Markdown
  • new behavior to detect which parser to use based on documentation file suffix (.md vs .org)
  • a new CLI flag (-type {md,org}) to select a parser explicitly (overriding file suffix, if any)
  • if no file provided, xc searches for either README.md and README.org in current directory & parents (with preference for README.md, if both exist, to minimize potential for breaking change; though breakage is still possible, given that the tool would currently skip over a directory containing README.org and find a parent containing README.md, but would stop earlier after this change)
  • documentation updates to support users of xc & org-mode

What's next?

I have tested it thus far by running go test ./... and by running it on various of my own org and md files. It could use some more testing.

At this stage I welcome feedback on any aspect of the approach, code organization, testing, etc. If you are worried about code duplication, I was thinking about doing another pass after getting the thing working to deduplicate and refactor the parsers somewhat. The approach I've favored has the benefit of minimizing code changes for Markdown users, reducing the potential to break the current behavior.

Notes on differences from md behavior

These are documented for end-users in ABOUT.org

  • Comment headings
    org-mode supports comment headings, which begin with COMMENT and are intended to be skipped over during execution. I've added some logic to honor this for headings that would otherwise be counted as task headings (see example here, and notice that in the rendered view GitHub correctly skips rendering that heading.)
  • Header tags
    org-mode has an explicit affordance for hidden markers attached to headlines: tags. I decided to look for a :xc_heading: tag on a heading rather than an HTML comment. Here's what it would look like in practice:
    ** Getting started                          :xc_heading:
      *** build
        [...etc]
    

@ryanprior ryanprior requested a review from joerdav as a code owner July 6, 2025 22:10
@ryanprior ryanprior changed the title Add org-parser module WIP: Add org-parser module Jul 6, 2025
@ryanprior ryanprior marked this pull request as draft July 6, 2025 22:13
@ryanprior ryanprior force-pushed the org-parser branch 5 times, most recently from 285e22b to ec4b117 Compare July 8, 2025 00:49
@ryanprior ryanprior changed the title WIP: Add org-parser module WIP: Add parseorg module Jul 8, 2025
@ryanprior ryanprior marked this pull request as ready for review July 12, 2025 05:34
@ryanprior ryanprior changed the title WIP: Add parseorg module Add parseorg module Jul 12, 2025
@ryanprior

Copy link
Copy Markdown
Contributor Author

@joerdav this is ready for review 🧾 😄

@joerdav

joerdav commented Oct 22, 2025

Copy link
Copy Markdown
Owner

This looks great, sorry it took some time for me to get to! I wonder if some mention of this in the docs might be helpful? Maybe a separate page that just outlines the differences.

@ryanprior

Copy link
Copy Markdown
Contributor Author

@joerdav no worries, lots going on in the world! I was just gathering some CI thoughts yesterday, so this is a good season to return to thinking about xc. I'll write up a page like you suggest.

* README.md:
  Updated to include references to org-mode in addition to Markdown
* New file: ABOUT.org
  Introduces using xc with org-mode and describes org-specific features
@joerdav

joerdav commented Oct 24, 2025

Copy link
Copy Markdown
Owner

Awesome, that's useful. My initial comment was around the documentation website that is generated from https://github.com/joerdav/xc/tree/main/doc and deployed to xcfile.dev I think this is the best place for this stuff to live! Thanks

- Updates timestamp to ISO standard (`hugo` was complaining)
- Links to org-mode feature explanation to doc website instead of on GitHub
- Removes ABOUT.org
@ryanprior

Copy link
Copy Markdown
Contributor Author

@joerdav I made a stab at updating the docs website. I viewed the it locally using hugo serve to ensure it works as expected. Happy to take any further notes!

@joerdav

joerdav commented Oct 27, 2025

Copy link
Copy Markdown
Owner

Great, I think this is ready now, thanks!

@joerdav joerdav merged commit 0f75768 into joerdav:main Oct 27, 2025
3 checks passed
@ryanprior ryanprior deleted the org-parser branch October 27, 2025 16:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants