README

jsx-readme

Generate Readme files with a React-like syntax and package.json-aware helpers.

🛠 Installation

Add jsx-readme and ts-node to your devDependencies.

npm i jsx-readme ts-node -D

Add these configs to your tsconfig.json:


{
  "compilerOptions": {
    "resolveJsonModule": true,
    "jsx": "react"
  }
}

Create a README.MD template (you may copy the example from this repo examples/README.md.tsx and edit to your taste). Add the following script to your package.json:


{
  "scripts": {
    "generate:readme": "ts-node README.md.tsx"
  }
}

🔬 Examples

package.json

{
  "name": "jsx-readme",
  "version": "0.0.0",
  "description": "Generate Readme files with a React-like syntax and package.json-aware helpers.",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "scripts": {
    "build": "rimraf lib && tsc -p tsconfig.build.json",
    "docs": "typedoc && touch docs/.nojekyll",
    "lint": "eslint src/**/*.ts src/**/*.tsx examples/**/*.tsx",
    "test": "jest && pkg-ok"
  },
  "engines": {
    "node": ">=12.4.0"
  },
  "files": [
    "lib"
  ],
  "keywords": [
    "Markdown",
    "generator",
    "JSX",
    "MD",
    "Readme"
  ],
  "author": "Daniel Bartholomae <daniel@bartholomae.name> (https://startup-cto.net)",
  "license": "MIT",
  "homepage": "https://dbartholomae.github.io/jsx-readme-test-fixture",
  "repository": "git@github.com:dbartholomae/jsx-readme-test-fixture.git",
  "bugs": "https://github.com/dbartholomae/jsx-readme-test-fixture/issues",
  "directories": {
    "lib": "lib",
    "doc": "docs",
    "example": "examples"
  },
  "dependencies": {
    "jsx-md": "^1.2.0"
  },
  "devDependencies": {
    "@commitlint/cli": "^9.1.2",
    "@commitlint/config-conventional": "^9.1.2",
    "@semantic-release/git": "^9.0.0",
    "@types/jest": "^26.0.10",
    "@types/react": "^16.9.49",
    "@typescript-eslint/eslint-plugin": "^4.1.0",
    "@typescript-eslint/parser": "^4.1.0",
    "eslint": "^7.8.1",
    "eslint-config-prettier": "^6.10.1",
    "eslint-plugin-prettier": "^3.1.2",
    "eslint-plugin-react": "^7.20.6",
    "husky": "^4.2.5",
    "jest": "^26.4.2",
    "lint-staged": "^10.2.13",
    "pkg-ok": "^2.3.1",
    "prettier": "^2.1.0",
    "rimraf": "^3.0.2",
    "semantic-release": "^17.1.1",
    "ts-jest": "^26.2.0",
    "tslib": "^2.0.1",
    "typedoc": "^0.19.1",
    "typedoc-plugin-param-names": "^1.0.2",
    "typedoc-plugin-sourcefile-url": "^1.0.6",
    "typescript": "^4.0.2"
  }
}

README.md.tsx

// We need to tell the JSX transpiler that in this file,
// instead of React we use the custom createElement and Fragment
// functions from jsx-readme
/* @jsx MD */
/* @jsxFrag Fragment */
import type { Component } from "jsx-readme";
import MD, {
  BadgesFromPkg,
  CodecovBadge,
  ContributingSection,
  DescriptionFromPkg,
  ExamplesFromPkg,
  Fragment,
  GithubWorkflowBadge,
  CLAAssistantBadge,
  HomepageFromPkg,
  renderToFile,
  TitleFromPkg,
  DiscordBadge,
  HacktoberfestBadge,
  LicenseBadge,
  LicenseFromPkg,
  ContributorsSectionFromPkg,
} from "jsx-readme";
import { CodeBlock, Heading, InlineCode, LineBreak } from "jsx-md";
import pkg from "./package.json";

const Readme: Component = () => (
  <Fragment>
    {/* Create a header with title, badges and description inferred from package.json */}
    <TitleFromPkg pkg={pkg} />
    <BadgesFromPkg pkg={pkg} />
    {/* Add additional badges. */}
    <LicenseBadge pkg={pkg} />
    <CodecovBadge pkg={pkg} />
    <GithubWorkflowBadge pkg={pkg} workflowName="Build and deploy" />
    <DiscordBadge
      inviteLink="https://discord.com/invite/X9HRSK5"
      serverId="750063320614174871"
    />
    <CLAAssistantBadge pkg={pkg} />
    <HacktoberfestBadge
      pkg={pkg}
      year={2020}
      suggestionLabel="good first issue"
    />
    <LineBreak />
    <DescriptionFromPkg pkg={pkg} />
    {/* You can use the components from jsx-md to build custom markdown. */}
    <Heading level={2}>🛠 Installation</Heading>
    Add <InlineCode>jsx-readme</InlineCode> and <InlineCode>ts-node</InlineCode>{" "}
    to your <InlineCode>devDependencies</InlineCode>.
    <LineBreak />
    <CodeBlock language="sh">npm i jsx-readme ts-node -D</CodeBlock>
    Add these configs to your <InlineCode>tsconfig.json</InlineCode>:
    <LineBreak />
    <CodeBlock language="json">
      {`
{
  "compilerOptions": {
    "resolveJsonModule": true,
    "jsx": "react"
  }
}
      `}
    </CodeBlock>
    Create a README.MD template (you may copy the example from this repo
    examples/README.md.tsx and edit to your taste). Add the following script to
    your <InlineCode>package.json</InlineCode>:
    <LineBreak />
    <CodeBlock language="json">
      {`
{
  "scripts": {
    "generate:readme": "ts-node README.md.tsx"
  }
}
      `}
    </CodeBlock>
    <LineBreak />
    <LineBreak />
    {/* Create an example section based on all files from the example directory set up in package.json */}
    <ExamplesFromPkg pkg={pkg} />
    {/* Create a section linking to the homepage from package.json */}
    <HomepageFromPkg pkg={pkg} />
    {/* Create a section linking to the contributing guidelines file */}
    <ContributingSection />
    {/* Create a section linking to the contributors of the repo */}
    <ContributorsSectionFromPkg pkg={pkg} />
    {/* Create a section linking to the license file. */}
    <LicenseFromPkg pkg={pkg} />
  </Fragment>
);

void renderToFile("./test/README.actual.md", <Readme />);