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

docs: use docusaurus-remark-plugin-tab-blocks to format tabs with code examples #12859

Merged
merged 37 commits into from May 31, 2022

Conversation

mrazauskas
Copy link
Contributor

@mrazauskas mrazauskas commented May 18, 2022

From #12848 (comment)

Summary

As mentioned in the comment, I wrote a Remark plugin which helps to avoid boilerplate for js/ts tabs in documentation.

This would be incredibly useful in configuration page. So perhaps, let‘s land this PR first? (If it does the job, of course.)

Todo

  • also replace Tabs and TabItem elsewhere in docs.

Test plan

Deploy preview.

@@ -25,9 +25,6 @@ import TOCInline from '@theme/TOCInline';

## Reference

import Tabs from '@theme/Tabs';
Copy link
Contributor Author

Choose a reason for hiding this comment

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

The plugin will add these too.

@mrazauskas
Copy link
Contributor Author

One more complex case has to stay. Tabs wrap two pieces of code here, have to think how to make it work. Probably that is alright for now?

https://github.com/facebook/jest/blob/43d075c12234bd4d128220814647908d1f682f9f/docs/MockFunctionAPI.md?plain=1#L199-L225

@mrazauskas mrazauskas marked this pull request as ready for review May 18, 2022 19:33
@mrazauskas
Copy link
Contributor Author

Deploy preview looks perfectly fine. Nice.

Copy link
Member

@SimenB SimenB left a comment

Choose a reason for hiding this comment

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

I like it! Landed the other PR first, but different files, so no conflict

@mrazauskas
Copy link
Contributor Author

mrazauskas commented May 19, 2022

Was thinking how improve this plugin. Here is the plan:

  • to make js tab title="some.test.js" work as expected
  • add a way to wrap few code blocks in one tab, e.g. js tab={"span": 2} title="first.test.js"

@mrazauskas mrazauskas marked this pull request as draft May 19, 2022 06:42
@mrazauskas
Copy link
Contributor Author

Done! The plugin supports tabs with multiple code blocks (through js tab={"span": 2} title="first.test.js") and titles are supported too:

Screenshot 2022-05-24 at 10 38 43

Also I added a test suite which runs before deploy. Felt like this is a good idea.

Screenshot 2022-05-24 at 10 35 38

@mrazauskas mrazauskas marked this pull request as ready for review May 24, 2022 07:45
website/src/remark/code-tabs-plugin.js Outdated Show resolved Hide resolved
Comment on lines 108 to 109
// eslint-disable-next-line consistent-return
return index + tabs.length;
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This return makes the visitor to skip traversing nodes which were just replaced with splice. Lint is complaining, but seems like all is good here.

The lint rule is turned off for ts and md files. Should apply for js only. It only prints a warning, so not sure if that is still useful. Perhaps?

console.log('this is second JS codeblock in a tab');
```

```ts tab={"span":2}
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I went for span, after considering group, include, next and something else. Sounded alright, but can be renamed as well. In a way, it defines a tab which spans two (or more) code blocks.

Also note that the next code block does not need any tab related meta data. Everything is configured through the first one.

Copy link
Member

@SimenB SimenB left a comment

Choose a reason for hiding this comment

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

this looks great! I'm not sure the plugin itself needs to live in this repo, tho?

@@ -0,0 +1,126 @@
/**
Copy link
Member

Choose a reason for hiding this comment

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

thoughts on publishing this outside of this repo?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I was thinking this way. It became more universal than I though in the beginning. Sounds fun to publish it separately. Why not? I will do that ;D

@mrazauskas mrazauskas marked this pull request as draft May 26, 2022 03:47
@mrazauskas mrazauskas marked this pull request as ready for review May 30, 2022 15:40
@mrazauskas mrazauskas changed the title docs: add custom plugin for tabs docs: use docusaurus-remark-plugin-tab-blocks to format tabs with code examples May 30, 2022
Copy link
Member

@SimenB SimenB left a comment

Choose a reason for hiding this comment

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

very nice!

@SimenB SimenB merged commit 2612e3e into jestjs:main May 31, 2022
@mrazauskas mrazauskas deleted the docs-tabs-plugin branch May 31, 2022 06:25
@mrazauskas
Copy link
Contributor Author

Indeed. In the end this is simple and nice. Thanks for the idea!

@github-actions
Copy link

github-actions bot commented Jul 1, 2022

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 1, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants