ドキュメントのReadmeマークダウンファイルの自動生成

Stencilは、マークダウンで readme.mdファイルを自動生成することができます。これはオプトイン機能であり、readmeファイルを兄弟として同じディレクトリ内のコンポーネントに保存します。この機能を使用すると、他の人が1つのコンポーネントに関するフォーマットされたドキュメントを簡単に見つけて読むことができます。特に、 readme.mdファイルがGithubのディレクトリ内に配置されると、デフォルトでreadmeマークダウンファイルがページのプライマリコンテンツになります。

readmeファイルを自動生成するには、 docs-readme出力ターゲットをstencil.config.tsに追加します。

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    { type: 'docs-readme' }
  ]
};

別のオプションは、次のようなフラグ --docs-readmeを追加することです。

stencil build --docs-readme

自動生成されたファイルへのカスタムマークダウンの追加

readme.mdファイルを生成したら、独自のマークダウンコンテンツでカスタマイズできます。 というコメントの上に独自のマークダウンを追加するだけです。

カスタムフッター

フッターの削除またはカスタマイズは、出力ターゲットに footerプロパティを追加することで実行できます。必要に応じて、マークダウンを使用してフッターを拡張できます。

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'docs-readme',
      footer: '*Built with love!*',
    }
  ]
};

ディレクトリへの生成

デフォルトでは、readmeファイルは対応するコンポーネントディレクトリに生成されます。この動作は、出力ターゲット構成の dirプロパティを介して変更できます。ディレクトリを指定すると、構造体 {dir}/{component}/readme.mdが作成されます。

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'docs-readme',
      dir: 'output'
    }
  ]
};

strictモード

出力ターゲット構成に strict:trueを追加すると、ドキュメントが不足しているプロジェクトがビルドされるたびに、Stencilが警告を出力します。

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'docs-readme',
      strict: true
    }
  ]
};