jserzanp / shaku Goto Github PK

Using the identification js annotate for each code block seems boring,When writing technical articles, we often say something like: "let's create a foo.js file."

• For example, we can giving a name to this code block, consider the following code snippet:

• We can also enhance its appearance through UI redesign to resemble the image below:

Is it necessary to add this feature?

I want annotate the code, together with twoslash

But currently twoslash and shaku both emits the HTML, so it is impossible to chain them up.

Motivation

Think about recording a video explaining a piece of code

1. need screen recording
2. need editing
3. upload somewhere
4. embed as video widget

The problem is Video is too heavy a tool for such use case, what we actually want is

1. a voice companion for the code snippet
2. a cursor to indicate where we are.

This actually could be achieved by recording two stream(voice stream, action stream) and put them together.

Design

1. recording

1. voice stream

Just use MediaStream api

https://developer.mozilla.org/en-US/docs/Web/API/MediaStream_Recording_API/Using_the_MediaStream_Recording_API

2. action stream

We only need to record the important actions, including

1. mouse click
2. selection
3. Shaku-specfic events

Shaku-specific events are events that triggers visual changes on code snippets, e.g.

1. highlight a line
2. toggle @ fold

Events must have location information attached to specific lines & characters.

2. Edit (low priority)

It should be feasible to cut the spaces between actions and voice.
If not able to do it automatically, we can at least edit manually.

3. Generating

Voice data and the event streams are bundled together, with time info on one single timeline.

3. Rendering

Just play the voice and events along the timeline.

For fast forward, we just increase the play speed.
For rewind, we need to start from the very start.

We need controls on the UI.

1. play
2. pause
3. progress bar

bring the Themes from Shaku Snippet to Shaku
https://shaku-web.vercel.app/snippet

And allow users to easily config themes

1. by code block
2. in plugin

🤔

After gathering enough use cases, we should consider creating a well-thought spec.

https://jser.dev/2023-08-09-effects-run-paint/#3-react-scheduler-tries-to-process-multiple-taskssync-before-yielding

We're developing a component example site that uses prettier and shaku, where prettier users format the code and will format comments related to shaku as well, resulting in a failure to get the results we expect. Currently, we can only partially disable prettier.

enable prettier

disable prettier

The whole project uses prettier, only the shaku related code snippets can't use prettier, which sucks.

I've come up with an option, but I'm not sure if it's optimal.

https://shaku-web.vercel.app/

if the color is green, // ( g ) is better than // ( 2)

like what react.dev is doing

https://github.com/reactjs/react.dev/blob/main/src/content/reference/react/useEffect.md?plain=1#L81

per title

https://github.com/shikijs/shiki

const shiki = require('shiki')

shiki
  .getHighlighter({
    theme: 'nord'
  })
  .then(highlighter => {
    console.log(highlighter.codeToHtml(`console.log('shiki');`, { lang: 'js' }))
  })

// <pre class="shiki nord" style="background-color: #2e3440"><code>
//   <!-- Highlighted Code -->
// </code></pre>

Similar to the code example in this blog post, we can achieve this effect by adjusting the opacity.

Referring to the @highlight syntax, I have implemented the @hidden syntax to achieve this effect.

https://shikiji.netlify.app/guide/transformers

Describe the bug
Not work when use with react, the code is as bellow,

class Code extends React.PureComponent {
    render(): React.ReactNode {
        return (
            <div className="buttons">
                {/* @highlight start */}
                <Button type="primary">主要</Button>
                <Button>次要</Button>
                <Button type="danger">危险</Button>
                <Button type="important">重要</Button>
                {/* @highlight end */}
            </div>
        );
    }
}

or

class Code extends React.PureComponent {
    render(): React.ReactNode {
        return (
            <div className="buttons">
                // @highlight start
                <Button type="primary">主要</Button>
                <Button>次要</Button>
                <Button type="danger">危险</Button>
                <Button type="important">重要</Button>
                // @highlight end
            </div>
        );
    }
}

but it works well as bellow,

class Code extends React.PureComponent {
    render(): React.ReactNode {
        return (
            // @highlight start
            <div className="buttons">
                <Button type="primary">主要</Button>
                <Button>次要</Button>
                <Button type="danger">危险</Button>
                <Button type="important">重要</Button>
            </div>
            // @highlight end
        );
    }
}

To Reproduce
shaku playground

Expected behavior
works well like this

Screenshots
If applicable, add screenshots to help explain your problem.

for example:

This helps build more robust tools.

I hope you can join some beginner's tutorials in readme,

this can help a lot of people to use these plug-ins,

i'd love to, but I don't know how yet.

https://github.com/huozhi/sugar-high

https://docusaurus.io/docs/markdown-features/code-blocks#highlighting-with-metadata-string

for comment block /* */ there is a dangling issue, especially for language like CSS/HTML

astro's code https://github.com/withastro/docs/blob/c00ca28f3ed53b44a43cb389aad6e9412e2d27fa/src/content/docs/en/guides/markdown-content.mdx#L631C1-L642

Currently it is not possible to annotate the shaku line.

need to vet each language