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

Display examples interleaved within reference docs #675

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

davepagurek
Copy link
Collaborator

@davepagurek davepagurek commented Jan 14, 2025

I made some updates to p5 here processing/p5.js#7466 and tested this with npm run custom:dev https://github.com/processing/p5.js.git#interleaved-examples on this branch.

\op
So the idea is to allow examples to be put in between other sections of the docs so they can stay more contextual.

In the reference, you can add the example tag to a code block like this:

Here are some docs

Here's an interleaved example:

```js example
console.log('test')
```

and here's more docs!

In processing/p5.js#7466, I tried pulling an example for image() up in between other stuff, and it looks like this:

image

Notes

  • It's parsing <pre><code class="example"> blocks out of the description rather than using a different JSON structure because that would invalidate the existing structure in the reference section of the site
  • It doesn't use quite the same syntax as before with @example at the end in the reference in the p5 codebase. Both can be used in one reference without issue at least
  • I'm not sure if the existing reference linting will work since this is part of the description body and not the examples section
  • I'm currently using a nasty regex to split the examples out of the description, that could definitely be cleaned up

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.

1 participant