ドキュメントの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 } ] };