10000 Demo file plugin by dwgray · Pull Request #2142 · bootstrap-vue-next/bootstrap-vue-next · GitHub
[go: up one dir, main page]
Skip to content

Demo file plugin #2142

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 5 commits into from
Aug 26, 2024
Merged

Demo file plugin #2142

merged 5 commits into from
Aug 26, 2024

Conversation

dwgray
Copy link
Member
@dwgray dwgray commented Aug 21, 2024 •
edited
Loading

Describe the PR

This PR sets up a system to clean up how we implement demos/examples in our docs.

  • I wrote a markdown-it plugin to override the snippet plugin syntax (<<< to take a DEMO marker, which will generate our entire demo section including the running demo and the syntax highlighted code with the single line + an external file.
  • I added and configured unplugin-vue-components to clean up the import statements in both the demos and the *.md files.
  • In addition, I used unplugin-vue-components to auto-register the demo components in markdown files, which removes the need to do any fancy footwork with adding import statements to the *.md files for those components.

Take a look at breadcrumb.md for an example of how this has cleaned up the markdown.

At this point, I believe the system is unambiguously better than it is currently. It's still set up so that we can incrementally move over to the new system and still use the old system if there are snippets that are small enough that we don't think it's necessary to have an external demo file.

I'm open to feedback on naming conventions/file structure for the demo files, but aside from that I believe this is ready to commit.

Background Info

I'm pretty frustrated with how the demos/examples in our docs work. There are two full copies of the code, one of which is split between the place where the demo is and the main script block and neither gets autoformatted correctly. I've looked at a number of markdown-it plugins but none seem to be well used or supported and I couldn't get any to work. The closest one I found was https://github.com/hairyf/markdown-it-vitepress-demo - I think it would do what I want if it worked, but it doesn't.

That sent me down the path of looking at what vitepress supports. They do support pulling a code snippet from a SFC file.

<template>
  <HighlightCard>
    <BreadcrumbOverview />
    <template #html>
  
  <<< ./demo/BreadcrumbOverview.vue
  
    </template>
  </HighlightCard>
</template>

<script setup lang="ts">
import BreadcrumbOverview from "./demo/BreadcrumbOverview.vue"
</script>

That solves the duplicate code + code formatting issue nicely. It does have the downside of having a bunch of little demo files floating around, but all of the solutions I've found do that.

It's also more verbose than I'd like.

I dug into vitepress' snippet plugin and found it pretty readable. I pulled that apart and rewrote their rule to let me do something like this:

<template>
<<< DEMO ./demo/BreadcrumbAsArray.vue
</template?

<script setup lang="ts">
import BreadcrumbOverview from "./demo/BreadcrumbOverview.vue"
</script>

It also still supports all of the line hightling, etc. that the vitepress snippet plugin does and doesn't interfere with the original plugin (it just has to run first, which it does).

I'm pretty happy with this solution. I'd like to take the time to see if I can get rid of the explicit import of the component and then I'd like to move forward with it. It has the advantage that it peacefully coexists with the existing system so I can convert over docs as I go through them for the parity pass.

Questions for @VividLemon:

  1. Does this logic make sense to you? Or is there something that's sending up a red flag?
  2. If you're good with this, do you have opinions on the file structure for the demo components?
  3. This has the advantage of making the code we display identical to the code that's running, but it doesn't expunge the somewhat redundant imports. Also, a bunch of our existing samples don't include the outer tags on the template block, while this always will. I can fix either or both of these by overriding Vitepress's fence render rule, but would rather not if you're all right with things as they are. This is also something that we can play with going forward if we go down this path, doesn't have to be solved on the initial round.

    Small replication

    N/A

    PR checklist

    What kind of change does this PR introduce? (check at least one)

    • Bugfix 🐛 - fix(...)
    • Feature - feat(...)
    • ARIA accessibility - fix(...)
    • Documentation update - docs(...)
    • Other (please describe)

    The PR fulfills these requirements:

    • Pull request title and all commits follow the Conventional Commits convention or has an override in this pull request body This is very important, as the CHANGELOG is generated from these messages, and determines the next version type. Pull requests that do not follow conventional commits or do not have an override will be denied

@bolt-new-by-stackblitz Bolt.new (by StackBlitz)
Copy link

Review PR in StackBlitz Codeflow Run & review this pull request in StackBlitz Codeflow.

dwgray
dwgray commented Aug 21, 2024
View reviewed changes
@dwgray dwgray marked this pull request as ready for review August 22, 2024 18:14
@VividLemon
Copy link
Member

I think it's a good change

@VividLemon VividLemon merged commit 584c145 into bootstrap-vue-next:main Aug 26, 2024
3 checks passed
@dwgray dwgray deleted the demo-file-plugin branch September 10, 2024 15:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@VividLemon VividLemon VividLemon approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@dwgray @VividLemon
0