refactor(docs): consolidate example code samples

[ranjan103]

Addresses #7163.

---

📚 Documentation preview 📚: https://volto--7198.org.readthedocs.build/

[boring-cyborg[bot]]

[!CAUTION] The Volto Team has suspended its review of new pull requests from first-time contributors until the release of Plone 7, which is preliminarily scheduled for the second quarter of 2026. Read details.

Thanks for submitting your first pull request! You are awesome! :hugs:

If you haven't done so already, read Plone's Code of Conduct, Contributing to Plone, First-time contributors, and Contributing to Volto, as this will greatly help the review process.

Welcome to the Plone community! :tada:

[stevepiercy]

@ranjan103 always discuss whether you should perform work before you proceed.

Although I personally would love to have code samples in docs actually tested—similar to what we do in the Python world—and this is an interesting approach, I don't know if the @plone/volto-team is interested in creating or maintaining such an effort.

[stevepiercy]

This PR creates new scripts that I think are unnecessary. We can run all three linters according to the Volto configuration, not just a custom implementation of one of them. See https://6.docs.plone.org/volto/contributing/linting.html and the proposal in the original issue #7163.

To try it out using all three linters, check out this branch, and run linters on the files.

pnpm lint "docs/source/_examples/**/*.jsx"
pnpm prettier "docs/source/_examples/**/*.jsx"
pnpm stylelint "docs/source/_examples/**/*.jsx"

From there, it would be trivial to add a Make command to run any or all of the linters, and therefore automate in CI. The only question I have is whether these commands when run from the root of the repo will pick up the linter configuration inside packages/volto, or if there are any other things to consider.

Setting aside the custom scripts, I see value in linting code examples in documentation, and this is a good demonstration of files to test it out on.

Ultimately, it's up to the @plone/volto-team to discuss if they want to put any effort into this approach going forward, or to create a bunch of first-timer issues to change the existing code examples in docs.

[sneridagh]

@stevepiercy @davisagli This approach does not allow to write code excerpts, and it will break most of the times because the imports would be incomplete, and ESlint won't be able to get the path for the real build. Let me ask you something? Do we have something like this in place for Python code in the Plone docs? I think we are overreaching in here and we are aiming for something that would make me don't write any piece of code in docs, and ultimatelly, don't want to write docs at all.

[stevepiercy]

@sneridagh you've completely changed your enthusiasm from https://github.com/plone/volto/issues/7163.

In the original issue, I mentioned:

Ultimately I'd love to run something similar to doctests and manuel for Python in documentation code samples, but for JS and JSX.

We do that now in plone.api.

I got this from a fellow documentarian that looks like a promising way to run linters on JS and JSX code samples inside the MyST file, not as separate files. Just set up our Volto linters, then use a Python subprocess to run the lint commands.

https://github.com/kai687/sphinxawesome-codelinter

[sneridagh]

@stevepiercy I think my enthusiasm continues being the same skeptical one :)