kf-markdown-list-ordered-list-cross-reference

Cross-referencing numbered lists in Markdown

Use this skill when creating or revising text that contains numbered lists in Markdown in a form that "requires little effort for number management and makes references between items hard to break."

When to use this skill

Use it for requests such as the following.

• You are writing or revising text that contains numbered lists, such as Markdown guides, notes, explanations, procedures, or runbooks
• You need item numbers, but you do not want to manually renumber every time you insert or reorder items
• You want later items to reference earlier items
• You want a Markdown template that contains numbered lists
• Topics such as Markdown, ordered lists, numbered lists, item numbers, anchors, internal links, and cross-references come up

Basic rules

1. In the source, write every ordered list item as 1. set to

In the Markdown source, write every item of an ordered list as 1. .

Reasons for this style:

• The Markdown renderer automatically assigns the displayed sequential numbers
• Even if you add or reorder items, you do not need to manually fix the numbers
• Diffs become smaller and easier to review

Example:

1. 端末を起動する
1. 設定ファイルを開く
1. サービスを再起動する

2. Reference items by anchor, not by displayed number

When a later item references an earlier item, do not write it using the displayed number such as "the third item" or "step 3"; instead, place an HTML anchor at the beginning of the target item and link to that anchor.

How to write it:

1. <span id="item-install-db"></span>データベースをインストールする
1. [データベースのインストール項目](#item-install-db)で設定したパスワードを入力する

Reasons for this practice:

• References are hard to break even if the order of items changes
• It is easy to jump to the reference target in Markdown previews such as GitHub
• The link text indicates "which item" it is, so it is easy to read

3. Use stable and easy-to-understand anchor names

Anchor naming rules:

• Add a prefix that matches the content (e.g., item-, section-, step-）
• Use short English words whose content is easy to infer
• Connect words with hyphens (kebab-case)
• Do not duplicate them within the same document

Good examples:

• item-prepare
• section-prerequisites
• step-restart-service

Examples to avoid:

• item-1
• item-before-this
• item-temp

Application procedure

When creating or revising a document, think in the following order.

1. Write every ordered list item in the Markdown source as 1. align to.
2. Find items that are referenced by later context, or items likely to be referenced in the future.
3. Immediately before the body of that item, insert <span id="..."></span> .
4. Rewrite cross-references as internal links such as [準備作業](#item-prepare) .
5. Make the link text an expression that shows the item's content or role, not the displayed number.
6. Check for duplicate anchor names or links to nonexistent targets.

Writing template

When writing a numbered list in a new document, first base it on the following form.

1. <span id="item-prepare"></span>準備作業を行う
1. 次のステップへ進む
1. [準備作業](#item-prepare)の結果を確認し、完了ボタンを押す

Guidelines for fixing existing documents

In documents where numbers are already explicitly shown as 1. 2. 3. , such as:

• Unify all numbers in the source to 1. unify to
• Unless there is a request to change the structure, do not change the order of items visible to users
• Replace fragile descriptions such as "see the second item" or "see step 2" with descriptive anchor links

When inserting a new item in the middle:

• Write the added item also as 1. write with
• Do not renumber the surrounding source numbers
• Review anchor names and link text only when necessary

Output policy

When creating or rewriting Markdown:

• Unless the user asks for an explanation, return the completed Markdown body as is
• Unless otherwise specified, use Japanese as the default output language
• Maintain the tone and style of the original document as much as possible
• Limit anchors to necessary items or items that are clearly likely to be referenced in the future
• HTMLは <span id="..."></span> Do not add them for purposes other than anchors via

Final check

Before finishing, check the following.

• All ordered list items are in the source as 1. has become
• Referenced items have unique anchors
• Internal links point to the corresponding #... is facing
• Link text describes the item content rather than the displayed number
• Even if items are added or reordered, it can be maintained without manual renumbering fixes