expressive-code-links 1.0.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -0
- package/dist/index.js +7 -3
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Links
|
|
2
|
+
|
|
3
|
+
A plugin for https://expressive-code.com/
|
|
4
|
+
|
|
5
|
+
Allows you to add links to code blocks, by prepending them with `\\`:
|
|
6
|
+
|
|
7
|
+
```js
|
|
8
|
+
// comes from \\[towc/expressive-code-links](https://github.com/towc/expressive-code-links)
|
|
9
|
+
import { pluginLink } from '\\[expressive-code-links]](https://github.com/towc/expressive-code-links)'
|
|
10
|
+
|
|
11
|
+
// can have multiple links in one line!
|
|
12
|
+
// usage as per \\[expressive code](https://expressive-code.com)'s \\[plugin documentation](https://expressive-code.com/reference/configuration/#plugins)
|
|
13
|
+
|
|
14
|
+
// so for \\[astro](https://astro.build/):
|
|
15
|
+
export default defineConfig({
|
|
16
|
+
integrations: [
|
|
17
|
+
expressiveCode({
|
|
18
|
+
plugins: [pluginLink()],
|
|
19
|
+
}),
|
|
20
|
+
],
|
|
21
|
+
})
|
|
22
|
+
|
|
23
|
+
// doesn't mess with other common syntax!
|
|
24
|
+
const array = [(x) => x]
|
|
25
|
+
const one = array[0](1)
|
|
26
|
+
|
|
27
|
+
const README = { md: 2 }
|
|
28
|
+
const \\[link](README.md) = 0
|
|
29
|
+
const two = array [link](README.md)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
For a live example, see https://yourweekly.dev/learn-sql-from-js#js-refresher, the astro article I wrote this plugin for.
|
|
35
|
+
|
|
36
|
+
## Customization
|
|
37
|
+
|
|
38
|
+
If you e.g. wanted the underline to look differently, you can select the link element like this:
|
|
39
|
+
|
|
40
|
+
```css
|
|
41
|
+
.ec-link {
|
|
42
|
+
text-decoration: dotted underline;
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
You might need to add `!important` if something else is targeting `a` elements with higher specificity in your site.
|
|
47
|
+
|
|
48
|
+
The [mdn docs for text-decoration](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-decoration) are a good read for options.
|
|
49
|
+
|
|
50
|
+
## Design choices
|
|
51
|
+
|
|
52
|
+
You might already have markdown link syntax showcased in your codeblocks, and I didn't want the plugin to mess with that, which is why the actual `a` element is created by "escaping" the markdown syntax from the code block into "actual" markdown.
|
|
53
|
+
|
|
54
|
+
The color of the link is inherited from what the underlying text should be. The `a.ec-link` element is otherwise completely vanilla, for accessibility and customizability.
|
|
55
|
+
|
|
56
|
+
## Bugs
|
|
57
|
+
|
|
58
|
+
- [ ] doesn't allow escaping of the link, e.g. `\\\\[link](href)` still renders as `\\link`
|
|
59
|
+
- not planning to implement, let me know if this affects you!
|
|
60
|
+
- [ ] breaks when spanning multiple elements
|
|
61
|
+
- not planning to fix, let me know if you have a legitimate usecase!
|
|
62
|
+
- [ ] doesn't auto-detect raw links like github
|
|
63
|
+
- not planning to implement. I would want to turn it off in my case.
|
|
64
|
+
|
|
65
|
+
## Contributing
|
|
66
|
+
|
|
67
|
+
I make no promises to keep this repository up to date.
|
|
68
|
+
|
|
69
|
+
You're free to create issues and PRs, but your best bet is to copy the index.ts file in your own project, if you want to make modifications.
|
package/dist/index.js
CHANGED
|
@@ -50,13 +50,17 @@ var LinkAnnotation = class extends ExpressiveCodeAnnotation {
|
|
|
50
50
|
}
|
|
51
51
|
render({ nodesToTransform }) {
|
|
52
52
|
return nodesToTransform.map((node) => {
|
|
53
|
-
if (node.type !== "element")
|
|
54
|
-
|
|
53
|
+
if (node.type !== "element") {
|
|
54
|
+
const getText = (el) => el.value ?? el.children?.map(getText).join("") ?? "";
|
|
55
|
+
throw new Error(
|
|
56
|
+
"[expressive-code-links]: Used link annotation spanning multiple expressive-code elements:\n " + getText(node)
|
|
57
|
+
);
|
|
58
|
+
}
|
|
55
59
|
return h(
|
|
56
60
|
node.tagName,
|
|
57
61
|
node.properties,
|
|
58
62
|
h(
|
|
59
|
-
"a",
|
|
63
|
+
"a.ec-link",
|
|
60
64
|
{
|
|
61
65
|
href: this.href,
|
|
62
66
|
style: "color: inherit"
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { definePlugin, ExpressiveCodeAnnotation, type AnnotationRenderOptions } from '@expressive-code/core'\nimport { h } from '@expressive-code/core/hast';\n\nfunction getRegex() {\n // ends up looking something like this: \n //\n // \\
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { definePlugin, ExpressiveCodeAnnotation, type AnnotationRenderOptions } from '@expressive-code/core'\nimport { h } from '@expressive-code/core/hast';\n\nfunction getRegex() {\n // ends up looking something like this: \n //\n // \\ [link ] (href )\n // /\\\\\\[(.+)\\]\\((.+)\\)/g\n\n const capture = (r: string) => '(' + r + ')';\n const escape = (c: string) => '\\\\' + c;\n const allExcept = (c: string) => '[^' + c + ']';\n const oneOrMore = (r: string) => r + '+';\n\n const surrounded = (start: string, wrapper: (x: string) => string, end: string) =>\n start + wrapper(oneOrMore(allExcept(end))) + end;\n\n const link = surrounded(escape('['), capture, escape(']'))\n const href = surrounded(escape('('), capture, escape(')'))\n\n // currently doesn't allow escaping the escape\n const regex = escape('\\\\') + link + href;\n\n return new RegExp(regex, 'g');\n}\n\nexport function pluginLink() {\n return definePlugin({\n name: 'Links inside code blocks, e.g. \\\\[link][href]',\n hooks: {\n preprocessCode: (context) => {\n for (const line of context.codeBlock.getLines()) {\n const matches = [...line.text.matchAll(getRegex())];\n\n // account for multiple links in one line\n let offset = 0;\n\n for (const match of matches) {\n const [original, link, href] = match;\n\n const from = (match.index || 0) - offset;\n const to = from + original.length;\n\n line.addAnnotation(\n new LinkAnnotation({\n href,\n inlineRange: {\n columnStart: from,\n columnEnd: to,\n }\n })\n )\n // this already culls annotation\n line.editText(from, to, link);\n\n offset += original.length - link.length;\n }\n }\n }\n },\n })\n}\n\nclass LinkAnnotation extends ExpressiveCodeAnnotation {\n href: string;\n constructor(options: ConstructorParameters<typeof ExpressiveCodeAnnotation>[0] & { href: string }) {\n const { href, ...original } = options;\n super(original);\n\n this.href = href;\n }\n render({ nodesToTransform }: AnnotationRenderOptions) {\n return nodesToTransform.map((node) => {\n if (node.type !== 'element') {\n // e.g.\n // con[st x](href) = 1\n // \n // If EC considers `const` as a separate `span` element from `x`,\n // which is needs to do to give them different colors,\n // then this bit of code will break.\n //\n // I'm not aware of any other applicable scenarios.\n\n type Node = object & { value?: string, children?: Node[] };\n\n const getText = (el: Node): string =>\n el.value ?? el.children?.map(getText).join('') ?? '';\n\n throw new Error(\n '[expressive-code-links]: Used link annotation spanning multiple expressive-code elements:\\n'\n + ' ' + getText(node)\n );\n }\n\n return h(\n node.tagName, \n node.properties,\n h(\n 'a.ec-link',\n {\n href: this.href,\n style: 'color: inherit',\n },\n ...node.children\n )\n )\n })\n }\n}\n\n"],"mappings":";AAAA,SAAS,cAAc,gCAA8D;AACrF,SAAS,SAAS;AAElB,SAAS,WAAW;AAMlB,QAAM,UAAU,CAAC,MAAc,MAAM,IAAI;AACzC,QAAM,SAAS,CAAC,MAAc,OAAO;AACrC,QAAM,YAAY,CAAC,MAAc,OAAO,IAAI;AAC5C,QAAM,YAAY,CAAC,MAAc,IAAI;AAErC,QAAM,aAAa,CAAC,OAAe,SAAgC,QACjE,QAAQ,QAAQ,UAAU,UAAU,GAAG,CAAC,CAAC,IAAI;AAE/C,QAAM,OAAO,WAAW,OAAO,GAAG,GAAG,SAAS,OAAO,GAAG,CAAC;AACzD,QAAM,OAAO,WAAW,OAAO,GAAG,GAAG,SAAS,OAAO,GAAG,CAAC;AAGzD,QAAM,QAAQ,OAAO,IAAI,IAAI,OAAO;AAEpC,SAAO,IAAI,OAAO,OAAO,GAAG;AAC9B;AAEO,SAAS,aAAa;AAC3B,SAAO,aAAa;AAAA,IAClB,MAAM;AAAA,IACN,OAAO;AAAA,MACL,gBAAgB,CAAC,YAAY;AAC3B,mBAAW,QAAQ,QAAQ,UAAU,SAAS,GAAG;AAC/C,gBAAM,UAAU,CAAC,GAAG,KAAK,KAAK,SAAS,SAAS,CAAC,CAAC;AAGlD,cAAI,SAAS;AAEb,qBAAW,SAAS,SAAS;AAC3B,kBAAM,CAAC,UAAU,MAAM,IAAI,IAAI;AAE/B,kBAAM,QAAQ,MAAM,SAAS,KAAK;AAClC,kBAAM,KAAK,OAAO,SAAS;AAE3B,iBAAK;AAAA,cACH,IAAI,eAAe;AAAA,gBACjB;AAAA,gBACA,aAAa;AAAA,kBACX,aAAa;AAAA,kBACb,WAAW;AAAA,gBACb;AAAA,cACF,CAAC;AAAA,YACH;AAEA,iBAAK,SAAS,MAAM,IAAI,IAAI;AAE5B,sBAAU,SAAS,SAAS,KAAK;AAAA,UACnC;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF,CAAC;AACH;AAEA,IAAM,iBAAN,cAA6B,yBAAyB;AAAA,EACpD;AAAA,EACA,YAAY,SAAuF;AACjG,UAAM,EAAE,MAAM,GAAG,SAAS,IAAI;AAC9B,UAAM,QAAQ;AAEd,SAAK,OAAO;AAAA,EACd;AAAA,EACA,OAAO,EAAE,iBAAiB,GAA4B;AACpD,WAAO,iBAAiB,IAAI,CAAC,SAAS;AACpC,UAAI,KAAK,SAAS,WAAW;AAY3B,cAAM,UAAU,CAAC,OACf,GAAG,SAAS,GAAG,UAAU,IAAI,OAAO,EAAE,KAAK,EAAE,KAAK;AAEpD,cAAM,IAAI;AAAA,UACR,kGACS,QAAQ,IAAI;AAAA,QACvB;AAAA,MACF;AAEA,aAAO;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL;AAAA,UACE;AAAA,UACA;AAAA,YACE,MAAM,KAAK;AAAA,YACX,OAAO;AAAA,UACT;AAAA,UACA,GAAG,KAAK;AAAA,QACV;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":[]}
|
package/package.json
CHANGED