Skip to content
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.

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

Add parsing and prettier support for @example tags in liquid doc #725

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

EvilGenius13
Copy link

@EvilGenius13 EvilGenius13 commented Jan 20, 2025

What are you adding in this PR?

References: https://github.com/Shopify/develop-advanced-edits/issues/471

Added support for parsing and formatting @example tags within LiquidDoc blocks.

Feedback

Right now, we aren't controlling whitespace for example tags. If someone wants to write check out. my great example, it would stay in that format. Should trim whitespace or allow people writing examples to have full control?

What's next? Any followup issues?

I want to add prettier support to automatically move @example tags and content below @param as it is the proper flow.

What did you learn?

AST's and CST's are quite puzzle to figure out.

Test

Example.tag.prettier.support.mp4

Before you deploy

  • I included a minor bump changeset
  • My feature is backward compatible

@EvilGenius13 EvilGenius13 marked this pull request as ready for review January 21, 2025 17:57
name: node.name,
position: position(node),
source: node.source,
exampleContent: {
Copy link
Contributor

Choose a reason for hiding this comment

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

locStart and locEnd will get out of sync if we do this, so we would either want to calculate that, or grab that data during the parsing step by updating our grammar

That way, we will have that information captured in the nodes themselves

expectPath(cst, '0.name').to.equal('doc');
expectPath(cst, '0.children.0.type').to.equal('LiquidDocExampleNode');
expectPath(cst, '0.children.0.name').to.equal('example');
expectPath(cst, '0.children.0.exampleContent.value').to.equal('hello there');
Copy link
Contributor

Choose a reason for hiding this comment

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

let's add some tests for locStart / locEnd and document how we want that to behave, especially considering whitespace etc

Can also add some assertions in stage-2 for position

.split('\n')
.map((line) => line.trim())
.filter(Boolean);
parts.push(join(hardline, lines));
Copy link
Contributor

Choose a reason for hiding this comment

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

might be able to clean this up depending on how we end up handling the trimming in earlier stages

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