5 |
6 | ### Commit Conventions
7 |
8 | When pushing or merging PRs in to main, your commit messages should follow the [Angular commit conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). At it's simplest, this looks something like `{type}: change this, add that`, where the commit `{type}` can be one of the following:
9 |
10 | | Commit Type | Description |
11 | | :--- | :--- |
12 | | `build` | creating a new release |
13 | | `chore` | assorted minor changes |
14 | | `ci` | updates related to the ci process |
15 | | `docs` | documentation updates |
16 | | `feat` | new elements; major features and updates |
17 | | `fix` | bug fixes; security updates |
18 | | `perf` | performance improvements |
19 | | `refactor` | general refactors |
20 | | `revert` | reverting a previous commit |
21 | | `style` | aesthetic changes |
22 | | `test` | adding or updating existing tests |
23 |
24 | You can also optionally note the `{scope}` of your changes in an additional parenthetical. If your changes require a longer description, feel free to add a commit message with further details! Combining all of these together, you might end up with something like:
25 |
26 | ```text
27 | feat(api-explorer): add color variants
28 |
29 | - some more details
30 | - about the changes
31 | ```
32 |
33 | ### Visual Regression Tests
34 |
35 | If you update the docs or the rendering changes, you'll need to update the snapshots. As most environments font configs are different, the simplest thing to do is grab the updated snapshots from the **Artifacts** section of your GitHub Actions workflow run (see [this failed workflow run](https://github.com/readmeio/markdown/actions/runs/1994189147) for an example).
36 |
37 | After a failed test, the updated snapshots should be available for download in the `image-snapshots` artifact. To update the snapshots, unzip the `image-snapshots` file and load its images into the `__tests__/browser/ci` directory. You can also view the (somewhat chaotic) image diffs in the `image-diffs` artifact.
38 |
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
1 | ARG NODE_VERSION=22.13
2 | FROM node:${NODE_VERSION}-alpine
3 |
4 | ARG NODE_VERSION
5 | ENV NODE_VERSION=$NODE_VERSION
6 |
7 | ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true
8 | ENV PUPPETEER_EXECUTABLE_PATH /usr/bin/chromium-browser
9 |
10 | RUN apk update && apk add \
11 | make \
12 | font-noto-emoji \
13 | font-roboto \
14 | chromium
15 |
16 | RUN npm install -g npm@10.5
17 |
18 | ENV DOCKER_WORKSPACE=/markdown
19 | WORKDIR ${DOCKER_WORKSPACE}
20 |
21 | COPY package.json package-lock.json ./
22 | RUN npm install
23 |
24 | COPY . ./
25 |
26 | RUN mkdir -p __tests__/browser/__image_snapshots__/__diff_output__
27 |
28 | EXPOSE 9966
29 |
30 | CMD ["test.browser"]
31 | ENTRYPOINT ["npm", "run"]
32 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Copyright (c) 2020, ReadMe
2 |
3 | Permission to use, copy, modify, and/or distribute this software for any purpose
4 | with or without fee is hereby granted, provided that the above copyright notice
5 | and this permission notice appear in all copies.
6 |
7 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
8 | REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
9 | FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
10 | INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
11 | OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
12 | TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
13 | THIS SOFTWARE.
14 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | -include .env
2 |
3 | .DEFAULT_GOAL := help
4 | .PHONY: help
5 | .EXPORT_ALL_VARIABLES:
6 |
7 | DOCKER_WORKSPACE := "/markdown"
8 | MOUNTS = --volume ${PWD}:${DOCKER_WORKSPACE} \
9 | --volume ${DOCKER_WORKSPACE}/node_modules
10 |
11 | build:
12 | docker build -t markdown $(dockerfile) --build-arg REACT_VERSION=${REACT_VERSION} .
13 |
14 | # This lets us call `make run test.browser`. Make expects cmdline args
15 | # to be targets. So this creates noop targets out of args. Copied from
16 | # SO.
17 | ifeq (run,$(firstword $(MAKECMDGOALS)))
18 | RUN_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
19 | $(eval $(RUN_ARGS):;@:)
20 | endif
21 |
22 | run: build ## Run npm scripts in a docker container. (default: make test.browser)
23 | docker run -it --rm ${MOUNTS} markdown $(RUN_ARGS)
24 |
25 | ci: build ## CI runner for `npm run test.browser -- --ci`
26 | # We don't mount root because CI doesn't care about live changes,
27 | # except for grabbing the snapshot diffs, so we mount __tests__.
28 | # Mounting root would break `make emoji` in the Dockerfile.
29 | docker run -i \
30 | --volume ${PWD}/__tests__:${DOCKER_WORKSPACE}/__tests__ \
31 | --env NODE_VERSION=${NODE_VERSION} \
32 | markdown test.browser -- --ci
33 |
34 | # I would like this to be `updateSnapshots` but I think it's better to
35 | # be consistent with jest.
36 | updateSnapshot: build ## Run `npm run test.browser -- --updateSnapshot`
37 | docker run -i --rm ${MOUNTS} markdown test.browser -- --updateSnapshot
38 |
39 | shell: build ## Docker shell.
40 | docker run -it --rm ${MOUNTS} --entrypoint /bin/bash markdown
41 |
42 | help: ## Show this help.
43 | @grep -E '^[a-zA-Z._-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
44 |
--------------------------------------------------------------------------------
/Procfile:
--------------------------------------------------------------------------------
1 | web: npx http-server example --port $PORT
2 |
--------------------------------------------------------------------------------
/__mocks__/.eslintrc:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "@readme/eslint-config/testing/jest"
3 | }
4 |
--------------------------------------------------------------------------------
/__mocks__/copy-to-clipboard.js:
--------------------------------------------------------------------------------
1 | const copy = jest.fn(() => true);
2 |
3 | module.exports = copy;
4 |
--------------------------------------------------------------------------------
/__tests__/.eslintrc:
--------------------------------------------------------------------------------
1 | {
2 | "extends": ["@readme/eslint-config/testing/jest.js", "@readme/eslint-config/testing/vitest.js"],
3 | "rules": {
4 | "testing-library/no-container": "off",
5 | "testing-library/no-node-access": "off"
6 | }
7 | }
8 |
--------------------------------------------------------------------------------
/__tests__/Glossary.test.tsx:
--------------------------------------------------------------------------------
1 | import { render, fireEvent, screen } from '@testing-library/react';
2 | import React from 'react';
3 |
4 | import { Glossary } from '../components/Glossary';
5 |
6 | test('should output a glossary item if the term exists', () => {
7 | const term = 'acme';
8 | const definition = 'This is a definition';
9 | const { container } = render(Title
11 |First Paragraph
12 |Second Paragraph
13 |Title
23 |First Paragraph
24 |Second Paragraph
25 |{'console.log("hi");'});
37 | const btn = screen.getByRole('button');
38 |
39 | expect(btn.parentNode?.nodeName.toLowerCase()).not.toBe('code');
40 | });
41 |
42 | it.skip('allows undefined children?!', () => {
43 | const { container } = render(
20 | `);
21 | });
22 |
23 | it('should render as a figure/figcaption if it has a caption', () => {
24 | render(
25 |
52 | | 11 | 12 | | 13 | 14 | | 15 | |
|---|---|---|
| 21 | 22 | | 23 | 24 | | 25 | |
| 29 | 30 | | 31 | 32 | | 33 | |
fish content
14 | 15 | 16 | ## Sanitizing html blocks 17 | 18 | [block:html] 19 | { 20 | "html": "" 21 | } 22 | [/block] 23 | -------------------------------------------------------------------------------- /__tests__/fixtures/table-of-contents-tests.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Table Of Contents Tests' 3 | category: 5fdf9fc9c2a7ef443e937315 4 | hidden: true 5 | --- 6 | 7 | # VariablesLocal Component
;
15 |
16 | Local Component
;
20 |
21 | Dynamic Component
36 | };
37 | ```
38 |
39 | export const Dynamic = () => {
40 | const ref = useRef();
41 |
42 | useEffect(() => {
43 | ref.current.classList.add('bg-gray-950', 'text-green-500', 'p-5', 'rounded-xl');
44 | }, [])
45 |
46 | return Dynamic Component
47 | };
48 |
49 | Some block html
7 | `;
8 |
9 | expect(mdast(text)).toMatchSnapshot();
10 | });
11 | });
12 |
--------------------------------------------------------------------------------
/__tests__/lib/exports/index.test.ts:
--------------------------------------------------------------------------------
1 | import { exports } from '../../../lib';
2 |
3 | import multipleExportsMdx from './input/multipleExports.mdx?raw';
4 | import singleExportMdx from './input/singleExport.mdx?raw';
5 | import weirdExportsMdx from './input/weirdExports.mdx?raw';
6 |
7 |
8 | describe('export tags', () => {
9 | it('returns a single export name', () => {
10 |
11 | expect(exports(singleExportMdx)).toStrictEqual(['Foo']);
12 | });
13 |
14 | it('returns multiple export names', () => {
15 |
16 | expect(exports(multipleExportsMdx)).toStrictEqual(['Foo', 'Bar']);
17 | });
18 |
19 | it('returns different types of export names', () => {
20 |
21 | expect(exports(weirdExportsMdx)).toStrictEqual(['Foo', 'bar', 'doSomethingFunction', 'YELLING', 'SingleNewlinesAreAnnoying', 'x', 'MyClass']);
22 | });
23 | });
--------------------------------------------------------------------------------
/__tests__/lib/exports/input/multipleExports.mdx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | export const Foo = () => {
4 | return Hello World
;
5 | }
6 |
7 | export const Bar = () => {
8 | return Hello World
;
5 | }
6 |
7 | ## Hey there
8 | Hello World
;
5 | }
6 |
7 | export const bar = () => {
8 | return Hello World
;
5 | }
6 |
7 | ## Hey there
8 | | 5 | Heading One 6 | | 7 | 8 |9 | Heading Two 10 | | 11 |
|---|---|
| 18 | * list item 19 | * list item 20 | | 21 | 22 |23 | :shrug: 24 | | 25 |
12 |
15 | \`}Item 1
13 | Item 2
14 | '; 12 | 13 | expect(tags(mdx)).toStrictEqual([]); 14 | }); 15 | 16 | it('returns block and phrasing content', () => { 17 | const mdx = ` 18 |
42 | 43 | */} 44 | " 45 | `); 46 | }); 47 | }); 48 | -------------------------------------------------------------------------------- /__tests__/migration/html-entities.test.ts: -------------------------------------------------------------------------------- 1 | import { migrate } from '../helpers'; 2 | 3 | describe('migrating html entities', () => { 4 | it('removes html entity spaces', () => { 5 | const md = ` 6 | { 7 | "json": true 8 | } 9 | `; 10 | const mdx = migrate(md); 11 | 12 | expect(mdx).toMatchInlineSnapshot(` 13 | "\\{\\ 14 | "json": true\\ 15 | } 16 | " 17 | `); 18 | }); 19 | }); 20 | -------------------------------------------------------------------------------- /__tests__/migration/image.test.ts: -------------------------------------------------------------------------------- 1 | import { migrate } from '../helpers'; 2 | 3 | describe('migrating images', () => { 4 | it('compiles images', () => { 5 | const md = ` 6 | [block:image] 7 | { 8 | "images": [ 9 | { 10 | "image": [ 11 | "https://fastly.picsum.photos/id/507/200/300.jpg?hmac=v0NKvUrOWTKZuZFmMlLN_7-RdRgeF-qFLeBGXpufxgg", 12 | "", 13 | "" 14 | ], 15 | "align": "center", 16 | "border": true 17 | } 18 | ] 19 | } 20 | [/block] 21 | `; 22 | 23 | const mdx = migrate(md); 24 | expect(mdx).toMatchInlineSnapshot(` 25 | "
17 |
22 | )
23 | }
24 |
25 | You clicked {count} times!
18 | 21 |{user.name}
; 28 | 29 | setIsOpen(!isOpen)}>
12 |
19 | );
20 | };
21 |
22 | export default Accordion;
23 |
24 |
--------------------------------------------------------------------------------
/components/Accordion/style.scss:
--------------------------------------------------------------------------------
1 | .Accordion {
2 | background: rgba(var(--color-bg-page-rgb, white), 1);
3 | border: 1px solid var(--color-border-default, rgba(black, 0.1));
4 | border-radius: 5px;
5 |
6 | &-title {
7 | align-items: center;
8 | background: rgba(var(--color-bg-page-rgb, white), 1);
9 | border: 0;
10 | border-radius: 5px;
11 | color: var(--color-text-default, #384248);
12 | cursor: pointer;
13 | display: flex;
14 | font-size: 16px;
15 | font-weight: 500;
16 | padding: 10px;
17 | position: relative;
18 | text-align: left;
19 | width: 100%;
20 |
21 | &:hover {
22 | background: var(--color-bg-hover, rgba(black, 0.05));
23 | }
24 |
25 | .Accordion[open] & {
26 | border-bottom-left-radius: 0;
27 | border-bottom-right-radius: 0;
28 | }
29 |
30 | &::marker {
31 | content: "";
32 | }
33 |
34 | &::-webkit-details-marker {
35 | display: none;
36 | }
37 | }
38 |
39 | &-toggleIcon,
40 | &-toggleIcon_opened {
41 | color: var(--color-text-minimum, #637288);
42 | font-size: 14px;
43 | margin-left: 5px;
44 | margin-right: 10px;
45 | transition: transform 0.1s;
46 |
47 | &_opened {
48 | transform: rotate(90deg);
49 | }
50 | }
51 |
52 | &-icon {
53 | color: var(--project-color-primary, inherit);
54 | margin-right: 10px;
55 | }
56 |
57 | &-content {
58 | color: var(--color-text-muted, #4f5a66);
59 | padding: 5px 15px 0 15px;
60 | }
61 | }
62 |
--------------------------------------------------------------------------------
/components/Callout/index.tsx:
--------------------------------------------------------------------------------
1 | import * as React from 'react';
2 |
3 | interface Props extends React.PropsWithChildren13 | 14 | {icon && } 15 | {title} 16 |
17 |{children}
18 | 40 |46 | ); 47 | }; 48 | 49 | export default Callout; 50 | -------------------------------------------------------------------------------- /components/Cards/index.tsx: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | 3 | import './style.scss'; 4 | 5 | interface CardProps 6 | extends React.PropsWithChildren<{ 7 | href?: string; 8 | icon?: string; 9 | iconColor?: string; 10 | target?: string; 11 | title?: string; 12 | }> {} 13 | 14 | export const Card = ({ children, href, icon, iconColor, target, title }: CardProps) => { 15 | const Tag = href ? 'a' : 'div'; 16 | return ( 17 |41 | {icon} 42 | {empty || React.Children.toArray(children)[0]} 43 |
44 | {React.Children.toArray(children).slice(1)} 45 |
{title}
} 20 |{children}
21 |
32 | {children}
33 |
34 | );
35 | };
36 |
37 | export default CardsGrid;
38 |
--------------------------------------------------------------------------------
/components/Cards/style.scss:
--------------------------------------------------------------------------------
1 | @import '/styles/mixins/dark-mode.scss';
2 |
3 | $iphone-plus: 414px;
4 |
5 | .CardsGrid {
6 | --Card-bg-color: rgba(var(--color-bg-page-rgb, white), 1);
7 | --Card-bg-color-hover: var(--color-bg-hover, #{rgba(black, 0.05)});
8 | --Card-border-color: var(--color-border-default, rgba(black, 0.1));
9 | --Card-shadow: 0 1px 2px #{rgba(black, 0.05)}, 0 2px 5px #{rgba(black, 0.02)};
10 | --Card-content-color: var(--color-text-muted, #4f5a66);
11 | --Card-icon-color: var(--project-color-primary, inherit);
12 | --Card-title-color: var(--color-text-default, #384248);
13 |
14 | @include dark-mode {
15 | --Card-icon-color: var(--color-primary-inverse, inherit);
16 | }
17 |
18 | display: grid;
19 | gap: 20px;
20 |
21 | .Card {
22 | padding: 15px;
23 | padding-bottom: 0;
24 | backdrop-filter: blur(20px);
25 | background: var(--Card-bg-color);
26 | border: 1px solid var(--Card-border-color);
27 | border-radius: 5px;
28 | box-shadow: var(--Card-shadow);
29 |
30 | &-top {
31 | display: inline-flex;
32 | flex-direction: row;
33 | }
34 |
35 | &-icon {
36 | color: var(--Card-icon-color);
37 | font-size: 20px;
38 | }
39 |
40 | &-title {
41 | color: var(--Card-title-color);
42 | font-weight: 600;
43 | margin-top: 10px;
44 |
45 | &:first-child {
46 | margin-top: 0;
47 | }
48 | }
49 |
50 | &-content {
51 | color: var(--Card-content-color);
52 | }
53 | }
54 |
55 | a.Card:not([href='']) {
56 | text-decoration: none;
57 | color: inherit;
58 |
59 | &:hover {
60 | background: var(--Card-bg-color-hover);
61 | }
62 | }
63 |
64 | @media (max-width: $iphone-plus) {
65 | grid-template-columns: 1fr !important;
66 | }
67 | }
68 |
--------------------------------------------------------------------------------
/components/Columns/index.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | import './style.scss';
4 |
5 | export const Column = ({ children }: React.PropsWithChildren) => {
6 | return {children}
;
7 | };
8 |
9 | interface Props extends React.PropsWithChildren<{ layout?: '1fr' | 'auto' | 'fixed' }> {}
10 |
11 | const Columns = ({ children, layout = 'auto' }: Props) => {
12 | // eslint-disable-next-line no-param-reassign
13 | layout = layout === 'fixed' ? '1fr' : 'auto';
14 | const columnsCount = React.Children.count(children);
15 |
16 | return (
17 |
18 | {children}
19 |
20 | );
21 | };
22 |
23 | export default Columns;
24 |
--------------------------------------------------------------------------------
/components/Columns/style.scss:
--------------------------------------------------------------------------------
1 | $iphone-plus: 414px;
2 |
3 | .Columns {
4 | display: grid;
5 | gap: var(--md, 20px);
6 |
7 | @media (max-width: $iphone-plus) {
8 | grid-template-columns: 1fr !important;
9 | }
10 | }
11 |
--------------------------------------------------------------------------------
/components/Glossary/index.tsx:
--------------------------------------------------------------------------------
1 | import type { GlossaryTerm } from '../../contexts/GlossaryTerms';
2 |
3 | import Tooltip from '@tippyjs/react';
4 | import React, { useContext } from 'react';
5 |
6 | import GlossaryContext from '../../contexts/GlossaryTerms';
7 |
8 | interface Props extends React.PropsWithChildren {
9 | term?: string;
10 | terms: GlossaryTerm[];
11 | }
12 |
13 | const Glossary = ({ children, term: termProp, terms }: Props) => {
14 | const term = (Array.isArray(children) ? children[0] : children) || termProp;
15 | const foundTerm = terms.find(i => term.toLowerCase() === i?.term?.toLowerCase());
16 |
17 | if (!foundTerm) return {term};
18 |
19 | return (
20 |
40 | {html}
41 |
42 | );
43 | }
44 |
45 | return ;
46 | };
47 |
48 | export default HTMLBlock;
49 |
--------------------------------------------------------------------------------
/components/Heading/index.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | export type Depth = 1 | 2 | 3 | 4 | 5 | 6;
4 |
5 | interface Props extends React.PropsWithChildren
17 | {children}
18 |
19 |
25 |
13 |
17 | );
18 | };
19 |
20 | export default Table;
21 |
--------------------------------------------------------------------------------
/components/Table/style.scss:
--------------------------------------------------------------------------------
1 | @mixin markdown-table(
2 | $row: #fff,
3 | $head: #f6f8fa,
4 | $stripe: #fbfcfd,
5 | $edges: #dfe2e5,
6 | ) {
7 | table {
8 | display: table;
9 | border-collapse: collapse;
10 | border-spacing: 0;
11 | width: 100%;
12 | color: var(--table-text);
13 |
14 | thead {
15 | color: var(--table-head-text, inherit);
16 | }
17 |
18 | thead tr {
19 | background: var(--table-head, #{$head});
20 | }
21 |
22 | tr {
23 | background-color: var(--table-row, #{$row});
24 | & + tr {
25 | border-top: 1px solid var(--table-edges, #{$edges});
26 | }
27 | }
28 |
29 | th,
30 | thead td {
31 | font-weight: 600;
32 | &:empty {
33 | padding: 0;
34 | }
35 | }
36 |
37 | td,
38 | th {
39 | padding: 0;
40 | color: inherit;
41 | vertical-align: middle;
42 | border: 1px solid var(--table-edges, #{$edges});
43 | padding: 6px 13px;
44 | > :first-child, > :only-child { margin-top: 0 !important }
45 | > :last-child, > :only-child { margin-bottom: 0 !important }
46 | }
47 |
48 | &:not(.plain) tr:nth-child(2n) {
49 | background-color: var(--table-stripe, #{$stripe});
50 | }
51 | }
52 | }
53 |
54 | .markdown-body {
55 | @include markdown-table;
56 |
57 | .rdmd-table {
58 | $border-wrap-width: 1px;
59 |
60 | & {
61 | display: block;
62 | position: relative;
63 | }
64 |
65 | &-inner {
66 | box-sizing: content-box;
67 | min-width: 100%;
68 | overflow: auto;
69 | width: 100%;
70 | }
71 |
72 | table {
73 | border: 1px solid var(--table-edges, #dfe2e5);
74 |
75 | &:only-child {
76 | margin: 0 !important;
77 |
78 | thead th {
79 | background: inherit;
80 | }
81 |
82 | td:last-child,
83 | th:last-child {
84 | border-right: none;
85 | }
86 |
87 | thead tr,
88 | thead th:last-child {
89 | box-shadow: 3px 0 0 var(--table-head);
90 | }
91 | }
92 | }
93 | }
94 | }
95 |
--------------------------------------------------------------------------------
/components/TableOfContents/index.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | function TableOfContents({ children }: React.PropsWithChildren) {
4 | return (
5 |
17 | );
18 | }
19 |
20 | export default TableOfContents;
21 |
--------------------------------------------------------------------------------
/components/TableOfContents/style.scss:
--------------------------------------------------------------------------------
1 | .toc-list {
2 | .glossary-tooltip {
3 | pointer-events: none;
4 | }
5 | }
6 |
--------------------------------------------------------------------------------
/components/Tabs/index.tsx:
--------------------------------------------------------------------------------
1 | import React, { useState } from 'react';
2 |
3 | import './style.scss';
4 |
5 | export const Tab = ({ children }: React.PropsWithChildren) => {
6 | return
14 | {children}
15 |
16 | {children}
;
7 | };
8 |
9 | interface TabsProps {
10 | children?: React.ReactElement[];
11 | }
12 |
13 | const Tabs = ({ children }: TabsProps) => {
14 | const [activeTab, setActiveTab] = useState(0);
15 |
16 | return (
17 |
18 |
19 |
36 |
37 | {children && children[activeTab]}
38 |
39 | );
40 | };
41 |
42 | export default Tabs;
43 |
--------------------------------------------------------------------------------
/components/Tabs/style.scss:
--------------------------------------------------------------------------------
1 | .TabGroup {
2 | &-nav {
3 | border-bottom: solid var(--color-border-default, #{rgba(black, 0.1)});
4 | margin-bottom: 15px;
5 | }
6 |
7 | &-tab {
8 | background: none;
9 | border: 0;
10 | color: var(--color-text-minimum, #637288);
11 | cursor: pointer;
12 | font-size: 15px;
13 | font-weight: 600;
14 | margin-right: 15px;
15 | padding: 0;
16 | padding-bottom: 10px;
17 |
18 | &_active {
19 | background: none;
20 | border: 0;
21 | border-bottom: solid var(--project-color-primary, var(--color-text-default, #384248));
22 | color: var(--project-color-primary, var(--color-text-default, #384248));
23 | font-size: 15px;
24 | font-weight: 600;
25 | margin-right: 15px;
26 | margin-bottom: -2px;
27 | padding: 0;
28 | padding-bottom: 10px;
29 | }
30 |
31 | &:hover {
32 | color: var(--color-text-muted, #4f5a66);
33 | }
34 | }
35 |
36 | &-icon {
37 | color: var(--project-color-primary, inherit);
38 | margin-right: 10px;
39 | }
40 |
41 | .TabContent {
42 | color: var(--color-text-muted, #4f5a66);
43 | }
44 | }
45 |
--------------------------------------------------------------------------------
/components/TailwindRoot/index.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | import { tailwindPrefix } from '../../utils/consts';
4 |
5 | interface Props extends React.PropsWithChildren<{ flow: boolean }> {}
6 |
7 | const TailwindRoot = ({ children, flow }: Props) => {
8 | const Tag = flow ? 'div' : 'span';
9 |
10 | return
35 |
43 | );
44 | };
45 |
46 | export default TutorialTile;
47 |
--------------------------------------------------------------------------------
/components/index.ts:
--------------------------------------------------------------------------------
1 | export { default as Accordion } from './Accordion';
2 | export { default as Anchor } from './Anchor';
3 | export { default as Callout } from './Callout';
4 | export { default as Cards, Card } from './Cards';
5 | export { default as Code } from './Code';
6 | export { default as CodeTabs } from './CodeTabs';
7 | export { default as Columns, Column } from './Columns';
8 | export { default as Embed } from './Embed';
9 | export { default as Glossary } from './Glossary';
10 | export { default as HTMLBlock } from './HTMLBlock';
11 | export { default as Heading } from './Heading';
12 | export { default as Image } from './Image';
13 | export { default as Table } from './Table';
14 | export { default as TableOfContents } from './TableOfContents';
15 | export { default as Tabs, Tab } from './Tabs';
16 | export { default as TailwindRoot } from './TailwindRoot';
17 | export { default as TailwindStyle } from './TailwindStyle';
18 | export { default as TutorialTile } from './TutorialTile';
19 |
--------------------------------------------------------------------------------
/contexts/BaseUrl.js:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | const BaseUrlContext = React.createContext('/');
4 |
5 | export default BaseUrlContext;
6 |
--------------------------------------------------------------------------------
/contexts/CodeOpts.ts:
--------------------------------------------------------------------------------
1 | import { createContext } from 'react';
2 |
3 | // used for the copyButtons prop
4 | const CodeOptsContext = createContext
36 |
37 |
42 |
38 |
39 |
40 |
41 |
32 |
33 | 34 | - Item Zed 35 | * Nested Item 36 | * Nested Item 37 | - Item One 38 | - Item Two 39 | 40 |
41 | Bulleted List
33 | 34 | - Item Zed 35 | * Nested Item 36 | * Nested Item 37 | - Item One 38 | - Item Two 39 | 40 |
42 |
43 | 44 | 1. Item Zed 45 | 1. Nested Numeric 46 | 1. Nested Numeric 47 | 1. Item One 48 | 2. Item Two 49 | 50 |
51 | Ordered List
43 | 44 | 1. Item Zed 45 | 1. Nested Numeric 46 | 1. Nested Numeric 47 | 1. Item One 48 | 2. Item Two 49 | 50 |
52 |
53 | 54 | - [ ] Task Zed 55 | - [x] Task One 56 | - [ ] Task Two 57 | 58 |
59 |
60 | ## Edge Cases
61 |
62 | ### Split Lists
63 |
64 | Seamlessly insert content blocks in between list items:
65 |
66 | 1. Item Zed
67 |
68 | > Sit excepturi doloremque deserunt maiores quam voluptatibus cupiditate delectus perferendis, ratione cum impedit rem recusandae inventore quibusdam et, tenetur aspernatur asperiores reiciendis soluta.
69 |
70 | 1. Item One
71 |
72 | ```javascript
73 | console.log('hello world')
74 | ```
75 |
76 | 1. Item Two
77 |
78 | ### Auto-Ordering
79 |
80 | Writing this will yield a properly ordered list:
81 |
82 | 1. Item Zed
83 | 1. Item One
84 | 1. Item Two
85 |
86 | Starting an ordered list with any number will increment continuously from that point, like so:
87 |
88 | 98. Starting in media res
89 | 98. Another list item
90 | 98. Yet another item
91 | [block:html]
92 | {
93 | "html": ""
94 | }
95 | [/block]
96 |
--------------------------------------------------------------------------------
/docs/mdx-components.mdx:
--------------------------------------------------------------------------------
1 | ## Tables
2 |
3 | You can use our `Table` component to match the ReadMe theming.
4 |
5 | ```jsx MDX
6 | export const table = [
7 | ['Left', 'Center', 'Right'],
8 | ['L0', '**bold**', '$1600'],
9 | ['L1', '`code`', '$12'],
10 | ['L2', '_italic_', '$1'],
11 | ];
12 |
13 | Check List
53 | 54 | - [ ] Task Zed 55 | - [x] Task One 56 | - [ ] Task Two 57 | 58 |
| {cell} | 18 | ))} 19 |
|---|
| {cell} | 26 | ))} 27 |
| {cell} | 45 | ))} 46 |
|---|
| {cell} | 53 | ))} 54 |
32 |
36 | ) : (
37 | children
38 | );
39 | }
40 | }
41 |
42 | export default RenderError;
43 |
--------------------------------------------------------------------------------
/example/Root.tsx:
--------------------------------------------------------------------------------
1 | import React, { useState } from 'react';
2 | import { useSearchParams } from 'react-router-dom';
3 |
4 | import Doc from './Doc';
5 | import Form from './Form';
6 | import Header from './Header';
7 |
8 | const Root = () => {
9 | const [theme, setTheme] = useState<'dark' | 'light' | 'system'>('system');
10 | const [searchParams] = useSearchParams();
11 | const ci = searchParams.has('ci');
12 |
13 | return (
14 |
33 | {message || error}
34 |
35 |
15 | {!ci &&
23 | );
24 | };
25 |
26 | export default Root;
27 |
--------------------------------------------------------------------------------
/example/components.ts:
--------------------------------------------------------------------------------
1 | const components = {
2 | Demo: `
3 | ## This is a Demo Component!
4 |
5 | > 📘 It can render JSX components!
6 | `,
7 | Test: `
8 | export const Test = ({ color = 'thistle' } = {}) => {
9 | return
17 |
22 |
18 | {!ci && }
19 |
21 |
10 | Hello, World!
11 |
;
12 | };
13 |
14 | export default Test;
15 | `,
16 | MultipleExports: `
17 | export const One = () => "One";
18 |
19 | export const Two = () => "Two";
20 | `,
21 | TailwindRootTest: `
22 | export const StyledComponent = () => {
23 | return
24 | Hello, World!
25 |
;
26 | }
27 | `,
28 | Steps: `
29 | export const Step = ({ children }) => {
30 | return (
31 |
32 |
36 | );
37 | };
38 |
39 |
33 | {children}
34 |
35 |
40 | {props.children}
41 |
42 | `,
43 |
44 | DarkMode: `
45 | import { useState } from 'react';
46 |
47 | export const DarkMode = () => {
48 | const [mode, setMode] = useState('dark');
49 |
50 | return (
51 |
52 |
59 |
66 | )
67 | }
68 | `,
69 | };
70 |
71 | export default components;
72 |
--------------------------------------------------------------------------------
/example/docs.ts:
--------------------------------------------------------------------------------
1 | import calloutTests from '../__tests__/fixtures/callout-tests.md';
2 | import childTests from '../__tests__/fixtures/child-tests.mdx';
3 | import codeBlockTests from '../__tests__/fixtures/code-block-tests.md';
4 | import exportTests from '../__tests__/fixtures/export-tests.mdx';
5 | import imageTests from '../__tests__/fixtures/image-tests.mdx';
6 | import sanitizingTests from '../__tests__/fixtures/sanitizing-tests.md';
7 | import tableOfContentsTests from '../__tests__/fixtures/table-of-contents-tests.md';
8 | import tailwindRootTests from '../__tests__/fixtures/tailwind-root-tests.mdx';
9 | import tutorialTile from '../__tests__/fixtures/tutorial-tile.mdx';
10 | import varsTest from '../__tests__/fixtures/variable-tests.md';
11 | import builtInComponents from '../docs/built-in-components.mdx';
12 | import callouts from '../docs/callouts.md';
13 | import codeBlocks from '../docs/code-blocks.md';
14 | import embeds from '../docs/embeds.md';
15 | import features from '../docs/features.md';
16 | import gettingStarted from '../docs/getting-started.md';
17 | import headings from '../docs/headings.md';
18 | import images from '../docs/images.md';
19 | import lists from '../docs/lists.md';
20 | import mdxComponents from '../docs/mdx-components.mdx';
21 | import mermaid from '../docs/mermaid.md';
22 | import tables from '../docs/tables.md';
23 |
24 | const lowerCase = (str: string) =>
25 | str.replaceAll(/([a-z])([A-Z])/g, (_: string, p1: string, p2: string) => `${p1} ${p2.toLowerCase()}`);
26 |
27 | const fixtures = Object.entries({
28 | calloutTests,
29 | callouts,
30 | childTests,
31 | codeBlockTests,
32 | codeBlocks,
33 | embeds,
34 | exportTests,
35 | features,
36 | gettingStarted,
37 | headings,
38 | images,
39 | imageTests,
40 | lists,
41 | mdxComponents,
42 | builtInComponents,
43 | mermaid,
44 | sanitizingTests,
45 | tableOfContentsTests,
46 | tables,
47 | tailwindRootTests,
48 | tutorialTile,
49 | varsTest,
50 | }).reduce((memo, [sym, doc]) => {
51 | const name = lowerCase(sym);
52 | memo[sym] = { name, doc };
53 | return memo;
54 | }, {});
55 |
56 | export default fixtures;
57 |
--------------------------------------------------------------------------------
/example/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/readmeio/markdown/78a978f4a4a602b66047386f132c483bf9d0f226/example/favicon.ico
--------------------------------------------------------------------------------
/example/img/nyt-thumbnail.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/readmeio/markdown/78a978f4a4a602b66047386f132c483bf9d0f226/example/img/nyt-thumbnail.jpg
--------------------------------------------------------------------------------
/example/img/pizzabro.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/readmeio/markdown/78a978f4a4a602b66047386f132c483bf9d0f226/example/img/pizzabro.jpg
--------------------------------------------------------------------------------
/example/img/readme-logo-white-on-blue.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/readmeio/markdown/78a978f4a4a602b66047386f132c483bf9d0f226/example/img/readme-logo-white-on-blue.png
--------------------------------------------------------------------------------
/example/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
63 | {mode} Mode Component
64 |
65 | next to all headings
18 | * for backwards-compatibility with how we used to do slugs.
19 | */
20 | function transformer(ast) {
21 | return flatMap(ast, node => {
22 | if (matchTag.test(node.tagName)) {
23 | // Parse the node texts to construct
24 | // a backwards-compatible anchor ID.
25 | const text = getTexts(node);
26 | const id = `section-${kebabCase(text)}`;
27 |
28 | if (id && !node?.properties?.id) {
29 | // Use the compat anchor ID as fallback if
30 | // GitHubs slugger returns an empty string.
31 | node.properties.id = id;
32 | }
33 |
34 | // Create and append a compat anchor element
35 | // to the section heading.
36 | const anchor = {
37 | type: 'element',
38 | tagName: 'div',
39 | properties: { id, className: 'heading-anchor_backwardsCompatibility' },
40 | };
41 | if (node.children) node.children.unshift(anchor);
42 | else node.children = [anchor];
43 | }
44 | return [node];
45 | });
46 | }
47 |
48 | module.exports = () => transformer;
49 |
--------------------------------------------------------------------------------
/processor/plugin/table-flattening.js:
--------------------------------------------------------------------------------
1 | const flatMap = require('unist-util-flatmap');
2 |
3 | const collectValues = ({ value, children }) => {
4 | if (value) return value;
5 | if (children) return children.flatMap(collectValues);
6 | return '';
7 | };
8 |
9 | const valuesToString = node => {
10 | const values = collectValues(node);
11 | return Array.isArray(values) ? values.join(' ') : values;
12 | };
13 |
14 | // Flattens table values and adds them as a seperate, easily-accessible key within children
15 | function transformer(ast) {
16 | return flatMap(ast, node => {
17 | if (node.tagName === 'table') {
18 | const [header, body] = node.children;
19 | // hAST tables are deeply nested with an innumerable amount of children
20 | // This is necessary to pullout all the relevant strings
21 | return [
22 | {
23 | ...node,
24 | children: [
25 | {
26 | ...node.children[0],
27 | value: valuesToString(header),
28 | },
29 | {
30 | ...node.children[1],
31 | value: valuesToString(body),
32 | },
33 | ],
34 | },
35 | ];
36 | }
37 |
38 | return [node];
39 | });
40 | }
41 |
42 | module.exports = () => transformer;
43 | module.exports.tableFlattening = transformer;
44 |
--------------------------------------------------------------------------------
/processor/transform/callouts.ts:
--------------------------------------------------------------------------------
1 | import type { Blockquote, Root } from 'mdast';
2 | import type { Callout } from 'types';
3 |
4 | import emojiRegex from 'emoji-regex';
5 | import { visit } from 'unist-util-visit';
6 |
7 | import { themes } from '../../components/Callout';
8 | import { NodeTypes } from '../../enums';
9 |
10 | const regex = `^(${emojiRegex().source}|⚠)(\\s+|$)`;
11 |
12 | const calloutTransformer = () => {
13 | return (tree: Root) => {
14 | visit(tree, 'blockquote', (node: Blockquote | Callout) => {
15 | if (!(node.children[0].type === 'paragraph' && node.children[0].children[0].type === 'text')) return;
16 |
17 | const startText = node.children[0].children[0].value;
18 | const [match, icon] = startText.match(regex) || [];
19 |
20 | if (icon && match) {
21 | const heading = startText.slice(match.length);
22 | const empty = !heading.length && node.children[0].children.length === 1;
23 | const theme = themes[icon] || 'default';
24 |
25 | node.children[0].children[0].value = heading;
26 |
27 | Object.assign(node, {
28 | type: NodeTypes.callout,
29 | data: {
30 | hName: 'Callout',
31 | hProperties: {
32 | icon,
33 | empty,
34 | theme,
35 | },
36 | },
37 | });
38 | }
39 | });
40 | };
41 | };
42 |
43 | export default calloutTransformer;
44 |
--------------------------------------------------------------------------------
/processor/transform/code-tabs.ts:
--------------------------------------------------------------------------------
1 | import type { BlockContent, Code, Node } from 'mdast';
2 | import type { CodeTabs } from 'types';
3 |
4 | import { visit } from 'unist-util-visit';
5 |
6 | import { NodeTypes } from '../../enums';
7 |
8 | const isCode = (node: Node): node is Code => node?.type === 'code';
9 |
10 | const codeTabsTransformer =
11 | ({ copyButtons }: { copyButtons?: boolean } = {}) =>
12 | (tree: Node) => {
13 | visit(tree, 'code', (node: Code) => {
14 | const { lang, meta, value } = node;
15 | node.data = {
16 | hProperties: { lang, meta, value, copyButtons },
17 | };
18 | });
19 |
20 | visit(tree, 'code', (node: Code, index: number, parent: BlockContent) => {
21 | if (parent.type === 'code-tabs' || !('children' in parent)) return;
22 |
23 | const length = parent.children.length;
24 | const children = [node];
25 | let walker = index + 1;
26 |
27 | while (walker <= length) {
28 | const sibling = parent.children[walker];
29 | if (!isCode(sibling)) break;
30 |
31 | const olderSibling = parent.children[walker - 1];
32 | if (olderSibling.position.end.offset + sibling.position.start.column !== sibling.position.start.offset) break;
33 |
34 | children.push(sibling);
35 | // eslint-disable-next-line no-plusplus
36 | walker++;
37 | }
38 |
39 | // If there is a single code block, and it has either a title or a
40 | // language set, let's display it by wrapping it in a code tabs block.
41 | // Othewise, we can leave early!
42 | if (children.length === 1 && !(node.lang || node.meta)) return;
43 |
44 | const codeTabs: CodeTabs = {
45 | type: NodeTypes.codeTabs,
46 | children,
47 | data: {
48 | hName: 'CodeTabs',
49 | },
50 | position: {
51 | start: children[0].position.start,
52 | end: children[children.length - 1].position.end,
53 | },
54 | };
55 |
56 | parent.children.splice(index, children.length, codeTabs);
57 | });
58 |
59 | return tree;
60 | };
61 |
62 | export default codeTabsTransformer;
63 |
--------------------------------------------------------------------------------
/processor/transform/compatability.ts:
--------------------------------------------------------------------------------
1 | import type { Emphasis, Image, Strong, Node, Parent } from 'mdast';
2 | import type { Transform } from 'mdast-util-from-markdown';
3 |
4 | import { phrasing } from 'mdast-util-phrasing';
5 | import { EXIT, SKIP, visit } from 'unist-util-visit';
6 |
7 | const strongTest = (node: Node): node is Emphasis | Strong => ['emphasis', 'strong'].includes(node.type);
8 |
9 | const compatibilityTransfomer = (): Transform => tree => {
10 | const trimEmphasis = (node: Emphasis | Strong) => {
11 | visit(node, 'text', child => {
12 | child.value = child.value.trim();
13 | return EXIT;
14 | });
15 |
16 | return node;
17 | };
18 |
19 | visit(tree, strongTest, node => {
20 | trimEmphasis(node);
21 | return SKIP;
22 | });
23 |
24 | visit(tree, 'image', (node: Image, index: number, parent: Parent) => {
25 | if (phrasing(parent) || !parent.children.every(child => child.type === 'image' || !phrasing(child))) return;
26 |
27 | parent.children.splice(index, 1, { type: 'paragraph', children: [node] });
28 | });
29 |
30 | return tree;
31 | };
32 |
33 | export default compatibilityTransfomer;
34 |
--------------------------------------------------------------------------------
/processor/transform/div.ts:
--------------------------------------------------------------------------------
1 | import type { TutorialTile } from '../../types';
2 | import type { Node, Parent } from 'mdast';
3 | import type { Transform } from 'mdast-util-from-markdown';
4 |
5 | import { visit } from 'unist-util-visit';
6 |
7 | import { NodeTypes } from '../../enums';
8 |
9 | const divTransformer = (): Transform => tree => {
10 | visit(tree, 'div', (node: Node, index, parent: Parent) => {
11 | const type = node.data?.hName;
12 |
13 | switch (type) {
14 | // Check if the div is a tutorial-tile in disguise
15 | case NodeTypes.tutorialTile:
16 | {
17 | // eslint-disable-next-line @typescript-eslint/no-unused-vars
18 | const { hName, hProperties, ...rest } = node.data;
19 | const tile = {
20 | ...rest,
21 | type: NodeTypes.tutorialTile,
22 | } as TutorialTile;
23 | parent.children.splice(index, 1, tile);
24 | }
25 | break;
26 | // idk what this is and/or just make it a paragraph
27 | default:
28 | node.type = type || 'paragraph';
29 | }
30 | });
31 |
32 | return tree;
33 | };
34 |
35 | export default divTransformer;
36 |
--------------------------------------------------------------------------------
/processor/transform/embeds.ts:
--------------------------------------------------------------------------------
1 | import type { Embed, EmbedBlock } from '../../types';
2 | import type { Paragraph, Parents, Node, Text } from 'mdast';
3 |
4 | import { visit } from 'unist-util-visit';
5 |
6 | import { NodeTypes } from '../../enums';
7 |
8 | const isEmbed = (node: Node): node is Embed => 'title' in node && node.title === '@embed';
9 |
10 | const embedTransformer = () => {
11 | return (tree: Node) => {
12 | visit(tree, 'paragraph', (node: Paragraph, i: number, parent: Parents) => {
13 | const [child] = node.children;
14 | if (!isEmbed(child)) return;
15 |
16 | const { url, title } = child;
17 | const label = (child.children[0] as Text).value;
18 |
19 | const newNode = {
20 | type: NodeTypes.embedBlock,
21 | label,
22 | title,
23 | url,
24 | data: {
25 | hProperties: {
26 | url,
27 | title: label ?? title,
28 | },
29 | hName: 'embed',
30 | },
31 | position: node.position,
32 | } as EmbedBlock;
33 |
34 | parent.children.splice(i, 1, newNode);
35 | });
36 | };
37 | };
38 |
39 | export default embedTransformer;
40 |
--------------------------------------------------------------------------------
/processor/transform/gemoji+.ts:
--------------------------------------------------------------------------------
1 | import type { FaEmoji, Gemoji } from '../../types';
2 | import type { Image, Root } from 'mdast';
3 |
4 | import { findAndReplace } from 'mdast-util-find-and-replace';
5 |
6 | import { NodeTypes } from '../../enums';
7 | import Owlmoji from '../../lib/owlmoji';
8 |
9 | const regex = /:(?\+1|[-\w]+):/g;
10 |
11 | const gemojiReplacer = (_, name: string) => {
12 | switch (Owlmoji.kind(name)) {
13 | case 'gemoji': {
14 | const node: Gemoji = {
15 | type: NodeTypes.emoji,
16 | value: Owlmoji.nameToEmoji[name],
17 | name,
18 | };
19 |
20 | return node;
21 | }
22 | case 'fontawesome': {
23 | const node: FaEmoji = {
24 | type: NodeTypes.i,
25 | value: name,
26 | data: {
27 | hName: 'i',
28 | hProperties: {
29 | className: ['fa-regular', name],
30 | },
31 | },
32 | };
33 |
34 | return node;
35 | }
36 | case 'owlmoji': {
37 | const node: Image = {
38 | type: 'image',
39 | title: `:${name}:`,
40 | alt: `:${name}:`,
41 | url: `/public/img/emojis/${name}.png`,
42 | data: {
43 | hProperties: {
44 | className: 'emoji',
45 | align: 'absmiddle',
46 | height: '20',
47 | width: '20',
48 | },
49 | },
50 | };
51 |
52 | return node;
53 | }
54 | default:
55 | return false;
56 | }
57 | };
58 |
59 | const gemojiTransformer = () => (tree: Root) => {
60 | findAndReplace(tree, [regex, gemojiReplacer]);
61 |
62 | return tree;
63 | };
64 |
65 | export default gemojiTransformer;
66 |
--------------------------------------------------------------------------------
/processor/transform/handle-missing-components.ts:
--------------------------------------------------------------------------------
1 | import type { CompileOpts } from '../../lib/compile';
2 | import type { Parents } from 'mdast';
3 | import type { Transform } from 'mdast-util-from-markdown';
4 | import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
5 |
6 | import { visit } from 'unist-util-visit';
7 |
8 | import * as Components from '../../components';
9 | import mdast from '../../lib/mdast';
10 | import { getExports, isMDXElement } from '../utils';
11 |
12 | type HandleMissingComponentsProps = Pick;
13 |
14 | const handleMissingComponents =
15 | ({ components, missingComponents }: HandleMissingComponentsProps): Transform =>
16 | tree => {
17 | const allComponents = new Set([
18 | ...getExports(tree),
19 | ...Object.keys(Components),
20 | ...Object.keys(components),
21 | ...Object.values(components).flatMap(doc => getExports(mdast(doc))),
22 | 'Variable',
23 | 'TutorialTile',
24 | ]);
25 |
26 | visit(
27 | tree,
28 | isMDXElement,
29 | (node: MdxJsxFlowElement | MdxJsxTextElement, index: number, parent: Parents) => {
30 | if (allComponents.has(node.name) || node.name.match(/^[a-z]/)) return;
31 |
32 | if (missingComponents === 'throw') {
33 | throw new Error(
34 | `Expected component \`${node.name}\` to be defined: you likely forgot to import, pass, or provide it.`,
35 | );
36 | }
37 |
38 | parent.children.splice(index, 1);
39 | },
40 | true,
41 | );
42 | };
43 |
44 | export default handleMissingComponents;
45 |
--------------------------------------------------------------------------------
/processor/transform/images.ts:
--------------------------------------------------------------------------------
1 | import type { ImageBlock } from '../../types';
2 | import type { Node, Paragraph, Parents, Image } from 'mdast';
3 | import type { MdxJsxFlowElement } from 'mdast-util-mdx';
4 |
5 | import { visit } from 'unist-util-visit';
6 |
7 | import { NodeTypes } from '../../enums';
8 | import { mdast } from '../../lib';
9 | import { getAttrs } from '../utils';
10 |
11 | const isImage = (node: Node): node is Image => node.type === 'image';
12 |
13 | const imageTransformer = () => (tree: Node) => {
14 | visit(tree, 'paragraph', (node: Paragraph, i: number, parent: Parents) => {
15 | // check if inline
16 | if (parent.type !== 'root' || node.children?.length > 1) return;
17 |
18 | const child = node.children[0];
19 | if (!isImage(child)) return;
20 |
21 | const { alt, url, title } = child;
22 |
23 | const attrs = {
24 | alt,
25 | title,
26 | children: [],
27 | src: url,
28 | };
29 |
30 | const newNode: ImageBlock = {
31 | type: NodeTypes.imageBlock,
32 | ...attrs,
33 | /*
34 | * @note: Using data.hName here means that we don't have to transform
35 | * this to an MdxJsxFlowElement, and rehype will transform it correctly
36 | */
37 | data: {
38 | hName: 'img',
39 | hProperties: attrs,
40 | },
41 | position: node.position,
42 | };
43 |
44 | parent.children.splice(i, 1, newNode);
45 | });
46 |
47 | const isImageBlock = (node: MdxJsxFlowElement) => node.name === 'Image';
48 |
49 | visit(tree, isImageBlock, (node: MdxJsxFlowElement) => {
50 | const attrs = getAttrs(node);
51 |
52 | if (attrs.caption) {
53 | // @ts-expect-error - @todo: figure out how to coerce RootContent[] to
54 | // the correct type
55 | node.children = mdast(attrs.caption).children;
56 | }
57 | });
58 |
59 | return tree;
60 | };
61 |
62 | export default imageTransformer;
63 |
--------------------------------------------------------------------------------
/processor/transform/index.ts:
--------------------------------------------------------------------------------
1 | import calloutTransformer from './callouts';
2 | import codeTabsTransformer from './code-tabs';
3 | import compatabilityTransfomer from './compatability';
4 | import divTransformer from './div';
5 | import embedTransformer from './embeds';
6 | import gemojiTransformer from './gemoji+';
7 | import handleMissingComponents from './handle-missing-components';
8 | import imageTransformer from './images';
9 | import injectComponents from './inject-components';
10 | import mdxToHast from './mdx-to-hast';
11 | import mermaidTransformer from './mermaid';
12 | import readmeComponentsTransformer from './readme-components';
13 | import readmeToMdx from './readme-to-mdx';
14 | import tablesToJsx from './tables-to-jsx';
15 | import tailwindTransformer from './tailwind';
16 | import variablesTransformer from './variables';
17 |
18 | export {
19 | compatabilityTransfomer,
20 | divTransformer,
21 | injectComponents,
22 | mdxToHast,
23 | mermaidTransformer,
24 | readmeComponentsTransformer,
25 | readmeToMdx,
26 | tablesToJsx,
27 | tailwindTransformer,
28 | handleMissingComponents,
29 | variablesTransformer,
30 | };
31 |
32 | export const defaultTransforms = {
33 | calloutTransformer,
34 | codeTabsTransformer,
35 | embedTransformer,
36 | imageTransformer,
37 | gemojiTransformer,
38 | };
39 |
40 | export default Object.values(defaultTransforms);
41 |
--------------------------------------------------------------------------------
/processor/transform/inject-components.ts:
--------------------------------------------------------------------------------
1 | import type { MdastComponents } from '../../types';
2 | import type { Parents } from 'mdast';
3 | import type { Transform } from 'mdast-util-from-markdown';
4 | import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
5 |
6 | import { visit } from 'unist-util-visit';
7 |
8 | import { isMDXElement } from '../utils';
9 |
10 | interface Options {
11 | components?: MdastComponents;
12 | }
13 |
14 | const inject =
15 | ({ components }: Options = {}) =>
16 | (node: MdxJsxFlowElement | MdxJsxTextElement, index: number, parent: Parents) => {
17 | if (!(node.name in components)) return;
18 |
19 | const { children } = components[node.name];
20 | parent.children.splice(index, children.length, ...children);
21 | };
22 |
23 | const injectComponents = (opts: Options) => (): Transform => tree => {
24 | visit(tree, isMDXElement, inject(opts));
25 |
26 | return tree;
27 | };
28 |
29 | export default injectComponents;
30 |
--------------------------------------------------------------------------------
/processor/transform/mdx-to-hast.ts:
--------------------------------------------------------------------------------
1 | import type { Parents } from 'mdast';
2 | import type { Transform } from 'mdast-util-from-markdown';
3 | import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
4 |
5 | import { visit } from 'unist-util-visit';
6 |
7 | import * as Components from '../../components';
8 | import { getAttrs, isMDXElement } from '../utils';
9 |
10 | const setData = (node: MdxJsxFlowElement | MdxJsxTextElement, index: number, parent: Parents) => {
11 | if (!node.name) return;
12 | if (!(node.name in Components)) return;
13 |
14 | parent.children[index] = {
15 | ...node,
16 | data: {
17 | hName: node.name,
18 | hProperties: getAttrs(node),
19 | },
20 | };
21 | };
22 |
23 | const mdxToHast = (): Transform => tree => {
24 | visit(tree, isMDXElement, setData);
25 |
26 | return tree;
27 | };
28 |
29 | export default mdxToHast;
30 |
--------------------------------------------------------------------------------
/processor/transform/mermaid.ts:
--------------------------------------------------------------------------------
1 | import type { Element } from 'hast';
2 | import type { Node } from 'unist';
3 |
4 | import { visit } from 'unist-util-visit';
5 |
6 | const mermaidTransformer = () => (tree: Node) => {
7 | visit(tree, 'element', (node: Element) => {
8 | if (node.tagName !== 'pre' || node.children.length !== 1) return;
9 |
10 | const [child] = node.children;
11 | if (child.type === 'element' && child.tagName === 'code' && child.properties.lang === 'mermaid') {
12 | node.properties = {
13 | ...node.properties,
14 | className: ['mermaid', ...((node.properties.className as string[]) || [])],
15 | };
16 | }
17 | });
18 |
19 | return tree;
20 | };
21 |
22 | export default mermaidTransformer;
23 |
--------------------------------------------------------------------------------
/processor/transform/reusable-content.js:
--------------------------------------------------------------------------------
1 | import { visit } from 'unist-util-visit';
2 |
3 | import { type } from '../parse/reusable-content-parser';
4 |
5 | function reusableContent() {
6 | const { wrap = true } = this.data('reusableContent');
7 |
8 | return tree => {
9 | if (wrap) return tree;
10 |
11 | visit(tree, type, (node, index, parent) => {
12 | parent.children.splice(index, 1, ...node.children);
13 | });
14 |
15 | return tree;
16 | };
17 | }
18 |
19 | export default reusableContent;
20 |
--------------------------------------------------------------------------------
/processor/transform/table-cell-inline-code.js:
--------------------------------------------------------------------------------
1 | import { SKIP, visit } from 'unist-util-visit';
2 |
3 | const rxEscapedPipe = /\\\|/g;
4 |
5 | /**
6 | * HAST Transformer that finds all inline code nodes within table cells and
7 | * unescapes any escaped pipe chars so that the editor outputs them without
8 | * escape chars.
9 | *
10 | * This appears to be a bug with remark-parse < ~8
11 | */
12 | const tableCellInlineCode = () => tree => {
13 | visit(tree, [{ tagName: 'th' }, { tagName: 'td' }], tableCellNode => {
14 | visit(tableCellNode, { tagName: 'code' }, inlineCodeNode => {
15 | const textNode = inlineCodeNode.children[0];
16 |
17 | if (textNode && rxEscapedPipe.test(textNode.value)) {
18 | textNode.value = textNode.value.replace(rxEscapedPipe, '|');
19 | }
20 | });
21 |
22 | return SKIP;
23 | });
24 | };
25 |
26 | export default tableCellInlineCode;
27 |
--------------------------------------------------------------------------------
/processor/transform/tailwind.tsx:
--------------------------------------------------------------------------------
1 | import type { PhrasingContent, BlockContent, Root } from 'mdast';
2 | import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
3 | import type { Plugin } from 'unified';
4 | import type { VFile } from 'vfile';
5 |
6 | import { visit, SKIP } from 'unist-util-visit';
7 |
8 | import { isMDXElement, toAttributes, getExports } from '../utils';
9 |
10 | interface TailwindRootOptions {
11 | components: Record;
12 | parseRoot?: boolean;
13 | }
14 |
15 | type Visitor =
16 | | ((node: MdxJsxFlowElement, index: number, parent: BlockContent) => undefined | void)
17 | | ((node: MdxJsxTextElement, index: number, parent: PhrasingContent) => undefined | void);
18 |
19 | const injectTailwindRoot =
20 | ({ components = {} }): Visitor =>
21 | (node, index, parent) => {
22 | if (!('name' in node)) return;
23 | if (!(node.name in components)) return;
24 | if (!('children' in parent)) return;
25 |
26 | const attrs = {
27 | flow: node.type === 'mdxJsxFlowElement',
28 | };
29 |
30 | const wrapper = {
31 | type: node.type,
32 | name: 'TailwindRoot',
33 | attributes: toAttributes(attrs),
34 | children: [node],
35 | };
36 |
37 | parent.children.splice(index, 1, wrapper);
38 |
39 | // eslint-disable-next-line consistent-return
40 | return SKIP;
41 | };
42 |
43 | const tailwind: Plugin<[TailwindRootOptions]> =
44 | ({ components }) =>
45 | (tree: Root, vfile: VFile) => {
46 | const localComponents = getExports(tree).reduce((acc, name) => {
47 | acc[name] = String(vfile);
48 | return acc;
49 | }, {});
50 |
51 | visit(tree, isMDXElement, injectTailwindRoot({ components: { ...components, ...localComponents } }));
52 |
53 | return tree;
54 | };
55 |
56 | export default tailwind;
57 |
--------------------------------------------------------------------------------
/sanitize.schema.js:
--------------------------------------------------------------------------------
1 | import { defaultSchema } from 'hast-util-sanitize/lib/schema';
2 |
3 | const createSchema = ({ safeMode } = {}) => {
4 | const schema = JSON.parse(JSON.stringify(defaultSchema));
5 |
6 | // Sanitization Schema Defaults
7 | schema.clobberPrefix = '';
8 |
9 | schema.tagNames.push('span');
10 | schema.attributes['*'].push('class', 'className', 'align');
11 | if (!safeMode) {
12 | schema.attributes['*'].push('style');
13 | }
14 |
15 | schema.tagNames.push('rdme-pin');
16 |
17 | schema.tagNames.push('rdme-embed');
18 | schema.attributes['rdme-embed'] = [
19 | 'url',
20 | 'provider',
21 | 'html',
22 | 'title',
23 | 'href',
24 | 'iframe',
25 | 'width',
26 | 'height',
27 | 'image',
28 | 'favicon',
29 | 'align',
30 | ];
31 |
32 | schema.attributes.a = ['href', 'title', 'class', 'className', 'download'];
33 |
34 | schema.tagNames.push('figure');
35 | schema.tagNames.push('figcaption');
36 |
37 | schema.tagNames.push('input'); // allow GitHub-style todo lists
38 | schema.ancestors.input = ['li'];
39 |
40 | return schema;
41 | };
42 |
43 | export default createSchema;
44 |
--------------------------------------------------------------------------------
/scripts/perf-test.js:
--------------------------------------------------------------------------------
1 | const childProcess = require('child_process');
2 | const { Blob } = require('node:buffer');
3 |
4 | const rdmd = require('..');
5 |
6 | const mdBuffer = childProcess.execSync('cat ./docs/*', { encoding: 'utf8' });
7 |
8 | const createDoc = bytes => {
9 | let doc = '';
10 |
11 | while (new Blob([doc]).size < bytes) {
12 | const start = Math.ceil(Math.random() * mdBuffer.length);
13 | doc += mdBuffer.slice(start, start + bytes);
14 | }
15 |
16 | return doc;
17 | };
18 |
19 | // https://stackoverflow.com/a/14919494
20 | function humanFileSize(bytes, si = false, dp = 1) {
21 | const thresh = si ? 1000 : 1024;
22 |
23 | if (Math.abs(bytes) < thresh) {
24 | return `${bytes} B`;
25 | }
26 |
27 | const units = si
28 | ? ['kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
29 | : ['KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
30 | let u = -1;
31 | const r = 10 ** dp;
32 |
33 | do {
34 | // eslint-disable-next-line no-param-reassign
35 | bytes /= thresh;
36 | // eslint-disable-next-line no-plusplus
37 | ++u;
38 | } while (Math.round(Math.abs(bytes) * r) / r >= thresh && u < units.length - 1);
39 |
40 | return `${bytes.toFixed(dp)} ${units[u]}`;
41 | }
42 |
43 | const max = 8;
44 |
45 | console.log('n : string size : duration');
46 |
47 | new Array(max).fill(0).forEach((_, i) => {
48 | const bytes = 10 ** i;
49 | const doc = createDoc(bytes);
50 | const then = Date.now();
51 |
52 | rdmd.mdast(doc);
53 | const duration = Date.now() - then;
54 |
55 | console.log(`${i} : ${humanFileSize(new Blob([doc]).size)} : ${duration / 1000} s`);
56 | });
57 |
--------------------------------------------------------------------------------
/stylelint.config.js:
--------------------------------------------------------------------------------
1 | module.exports = {
2 | extends: '@readme/stylelint-config',
3 | rules: {
4 | 'alpha-value-notation': null,
5 | },
6 | };
7 |
--------------------------------------------------------------------------------
/styles/components.scss:
--------------------------------------------------------------------------------
1 | @import '../components/Image/style';
2 | @import '../components/Table/style';
3 | @import '../components/TableOfContents/style';
4 | @import '../components/Code/style';
5 | @import '../components/CodeTabs/style';
6 | @import '../components/Callout/style';
7 | @import '../components/Heading/style';
8 | @import '../components/Embed/style';
9 | @import '../components/Glossary/style';
10 |
--------------------------------------------------------------------------------
/styles/main.scss:
--------------------------------------------------------------------------------
1 | @import './gfm';
2 | @import './components';
3 |
4 | :root {
5 | // --markdown-radius: 3px;
6 | // --markdown-edge: #eee;
7 | --markdown-text: inherit;
8 | --markdown-title: inherit;
9 | --markdown-title-font: inherit;
10 | --markdown-font: inherit;
11 | --markdown-font-size: inherit;
12 | --markdown-line-height: 1.5;
13 | }
14 |
15 | .field-description,
16 | .markdown-body {
17 | @include gfm;
18 |
19 | font-size: var(--markdown-font-size, 14px);
20 | }
21 |
--------------------------------------------------------------------------------
/styles/mixins/dark-mode.scss:
--------------------------------------------------------------------------------
1 | /* We’re planning to move this in to the monorepo in which case
2 | we could share the dark mode mix in. Kelly is planning to take
3 | some time to make that move so can we add a comment here to
4 | circle back on this at that point?
5 |
6 | - Rafe
7 | April 2025
8 | */
9 |
10 | @mixin dark-mode($global: false) {
11 | $root: &;
12 |
13 | @if not $root {
14 | [data-color-mode='dark'] {
15 | @content;
16 | }
17 |
18 | [data-color-mode='auto'],
19 | [data-color-mode='system'] {
20 | @media (prefers-color-scheme: dark) {
21 | @content;
22 | }
23 | }
24 | } @else if $global {
25 | :global([data-color-mode='dark']) & {
26 | @content;
27 | }
28 |
29 | :global([data-color-mode='auto']) &,
30 | :global([data-color-mode='system']) & {
31 | @media (prefers-color-scheme: dark) {
32 | @content;
33 | }
34 | }
35 | } @else {
36 | [data-color-mode='dark'] & {
37 | @content;
38 | }
39 |
40 | [data-color-mode='auto'] &,
41 | [data-color-mode='system'] & {
42 | @media (prefers-color-scheme: dark) {
43 | @content;
44 | }
45 | }
46 | }
47 | }
48 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "allowSyntheticDefaultImports": true,
4 | "baseUrl": "./",
5 | "checkJs": false,
6 | "declaration": true,
7 | "isolatedModules": true,
8 | "jsx": "react",
9 | "lib": [
10 | "ES2022",
11 | "DOM", // Loaded to our global type availability for access to `fetch`.
12 | "DOM.iterable"
13 | ],
14 | "module": "es2022",
15 | "moduleResolution": "Bundler",
16 | "outDir": "dist",
17 | "resolveJsonModule": true,
18 | "sourceMap": true,
19 | "target": "ES2022"
20 | },
21 | "include": ["./index.ts", "./options.js", "./components", "./contexts", "./example", "./lib", "./processor"],
22 | "exclude": ["node_modules", "dist"]
23 | }
24 |
--------------------------------------------------------------------------------
/utils/consts.ts:
--------------------------------------------------------------------------------
1 | export const tailwindPrefix = 'readme-tailwind';
2 |
--------------------------------------------------------------------------------
/utils/user.ts:
--------------------------------------------------------------------------------
1 | interface Default {
2 | default: string;
3 | name: string;
4 | }
5 |
6 | export interface Variables {
7 | defaults: Default[];
8 | user: Record;
9 | }
10 |
11 | const User = (variables?: Variables) => {
12 | const { user = {}, defaults = [] } = variables || {};
13 |
14 | return new Proxy(user, {
15 | get(target, attribute) {
16 | if (typeof attribute === 'symbol') {
17 | return '';
18 | }
19 |
20 | if (attribute in target) {
21 | return target[attribute];
22 | }
23 |
24 | const def = defaults.find((d: Default) => d.name === attribute);
25 |
26 | return def ? def.default : attribute.toUpperCase();
27 | },
28 | });
29 | };
30 |
31 | export default User;
32 |
--------------------------------------------------------------------------------
/vitest-setup.js:
--------------------------------------------------------------------------------
1 | /* eslint-disable import/no-extraneous-dependencies */
2 | import '@testing-library/jest-dom';
3 | import '@testing-library/jest-dom/vitest';
4 |
5 | import './__tests__/matchers';
6 |
--------------------------------------------------------------------------------
/vitest.config.mts:
--------------------------------------------------------------------------------
1 | /* eslint-disable import/no-extraneous-dependencies */
2 | import react from '@vitejs/plugin-react';
3 | import { defineConfig } from 'vitest/config';
4 |
5 | export default defineConfig({
6 | plugins: [react()],
7 | test: {
8 | environment: 'jsdom',
9 | exclude: ['**/node_modules/**', '**/dist/**'],
10 | globals: true,
11 | setupFiles: ['./vitest-setup.js'],
12 | workspace: [
13 | {
14 | extends: true,
15 | test: {
16 | exclude: ['__tests__/browser'],
17 | name: 'rdmd',
18 | },
19 | },
20 | ],
21 | },
22 | });
23 |
--------------------------------------------------------------------------------
/vitest.d.ts:
--------------------------------------------------------------------------------
1 | interface CustomMatchers {
2 | toStrictEqualExceptPosition: () => R;
3 | }
4 |
5 | declare module 'vitest' {
6 | interface Assertion extends CustomMatchers {}
7 | interface AsymmetricMatchersContaining extends CustomMatchers {}
8 | }
9 |
--------------------------------------------------------------------------------
/webpack.common.js:
--------------------------------------------------------------------------------
1 | /* eslint-disable import/no-extraneous-dependencies
2 | */
3 | const ExtractCSS = require('mini-css-extract-plugin');
4 | const sass = require('sass');
5 | const webpack = require('webpack');
6 |
7 | module.exports = {
8 | plugins: [
9 | new ExtractCSS({
10 | filename: '[name].css',
11 | }),
12 | new webpack.ProvidePlugin({
13 | Buffer: ['buffer', 'Buffer'],
14 | }),
15 | new webpack.ProvidePlugin({
16 | process: 'process/browser',
17 | }),
18 | ],
19 | module: {
20 | rules: [
21 | {
22 | test: /\.tsx?$/,
23 | use: {
24 | loader: 'ts-loader',
25 | },
26 | exclude: /node_modules/,
27 | },
28 | {
29 | test: /\.jsx?$/,
30 | exclude: /node_modules\/(?!@readme\/[\w-]+\/)/,
31 | use: {
32 | loader: 'babel-loader',
33 | },
34 | },
35 | {
36 | test: /\.m?js$/,
37 | include: /node_modules/,
38 | type: 'javascript/auto',
39 | resolve: {
40 | fullySpecified: false,
41 | },
42 | },
43 | { test: /tailwindcss\/.*\.css$/, type: 'asset/source' },
44 | {
45 | test: /\.css$/,
46 | exclude: /tailwindcss\/.*\.css$/,
47 | use: [ExtractCSS.loader, 'css-loader'],
48 | },
49 | {
50 | test: /\.scss$/,
51 | use: [
52 | ExtractCSS.loader,
53 | 'css-loader',
54 | {
55 | loader: 'sass-loader',
56 | options: {
57 | implementation: sass,
58 | },
59 | },
60 | ],
61 | },
62 | {
63 | test: /\.(ttf|eot|svg|woff(2)?)(\?[a-z0-9=&.]+)?$/,
64 | exclude: /(node_modules)/,
65 | use: {
66 | loader: 'file-loader',
67 | options: {
68 | name: 'dist/fonts/[hash].[ext]',
69 | },
70 | },
71 | },
72 | ],
73 | },
74 | resolve: {
75 | extensions: ['.js', '.json', '.jsx', '.ts', '.tsx', '.md', '.css'],
76 | fallback: { buffer: require.resolve('buffer'), util: require.resolve('util/') },
77 | },
78 | };
79 |
--------------------------------------------------------------------------------
/webpack.dev.js:
--------------------------------------------------------------------------------
1 | /* eslint-disable import/no-extraneous-dependencies
2 | */
3 | const path = require('path');
4 |
5 | const webpack = require('webpack');
6 | const { merge } = require('webpack-merge');
7 |
8 | const common = require('./webpack.common');
9 |
10 | const config = merge(common, {
11 | entry: {
12 | demo: './example/index.tsx',
13 | },
14 | output: {
15 | path: path.resolve(__dirname, 'example/'),
16 | filename: '[name].js',
17 | },
18 | devServer: {
19 | static: './example',
20 | compress: true,
21 | port: 9966,
22 | hot: true,
23 | },
24 | devtool: 'eval',
25 | module: {
26 | rules: [
27 | {
28 | test: /\.(txt|mdx?)$/i,
29 | type: 'asset/source',
30 | },
31 | ],
32 | },
33 | plugins: [
34 | new webpack.ProvidePlugin({
35 | process: 'process/browser',
36 | }),
37 | ],
38 | resolve: {
39 | fallback: {
40 | fs: require.resolve('browserify-fs'),
41 | path: require.resolve('path-browserify'),
42 | stream: require.resolve('stream-browserify'),
43 | },
44 | },
45 | });
46 |
47 | module.exports = config;
48 |
--------------------------------------------------------------------------------