jsx-readme로 README 파일 자동 생성

npm 패키지를 볼 때 가장 먼저 맞이하는 것은 npm 자체에 있든 GitHub의 소스에 있든 README.md 파일입니다. 그러나 당신이 나와 같다면 문서 작성은 유지 관리 및 업데이트는 고사하고 강력한 도구가 될 수 없습니다.

코드가 변경될 때마다 README 파일을 수동으로 업데이트하는 대신 README가 자동으로 최신 상태를 유지할 수 있다면 어떨까요? 추가해야 하는 배지를 기억하는 대신 이 모든 작업이 완료되면 어떻게 될까요?

jsx-readme 소개

다음은 jsx-readme 사용 예입니다.

// 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,
  DescriptionFromPkg,
  ExamplesFromPkg,
  Fragment,
  GithubWorkflowBadge,
  HomepageFromPkg,
  renderToFile,
  TitleFromPkg,
} from "jsx-readme";
import { 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. */}
    <CodecovBadge pkg={pkg} />
    <GithubWorkflowBadge pkg={pkg} workflowName="Build and deploy" />
    <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> to your{" "}
    <InlineCode>devDependencies</InlineCode> and install it. I recommend using
    it with <InlineCode>ts-node</InlineCode>. Then all you need to do is add a
    file like in the example below and run it via{" "}
    <InlineCode>ts-node</InlineCode> whenever you want to create a new version
    of the <InlineCode>README</InlineCode>.
    <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} />
  </Fragment>
);

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

보시다시피 jsx-readme는 React와 유사한 JSX 구문을 사용하여 Markdown을 정의합니다. 필요에 따라 독립적으로 또는 jsx-md와 함께 사용할 수도 있는 jsx-readme 위에 구축되었습니다.

JSX는 기본적으로 JavaScript이므로 이 파일에서 원하는 모든 작업을 수행할 수 있습니다. 이 간단한 경우에는 로컬package.json 파일을 가져와서 읽기만 하면 되지만 e. g. GitHub API를 쿼리하여 누가 기여했는지 파악한 다음 읽어보기에 추가하시겠습니까?

그리고 그냥 TypeScript 파일이기 때문에 e를 통해 간단히 실행할 수 있습니다. g. ts-node 또 다른 CLI 도구를 배울 필요가 없습니다.

그래서 어떻게 생겼습니까?

위 스크립트의 결과를 이해하는 가장 좋은 방법은 the package itself - jsx-readme가 이를 사용하여 자체 README를 만드는 것입니다.