mcpField
D
dotnet-github-docs

dotnet-github-docs

github.com/wshaddix开发8670 次安装35 周前更新
代码仓库

关于 dotnet-github-docs

为 .NET 仓库设计 GitHub 原生文档结构的技能，涵盖 README、贡献指南、议题与 PR 模板、仓库元数据及 GitHub Pages 仓库配置。

主要功能

  1. 01README 结构与徽章
  2. 02CONTRIBUTING.md 指南
  3. 03YAML 议题模板与 PR 模板
  4. 04GitHub Pages 仓库配置
  5. 05仓库元数据与 Mermaid 嵌入

适用场景

  1. 01为 .NET 仓库搭建文档结构
  2. 02统一议题和拉取请求的提交方式
  3. 03准备 README 架构图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wshaddix/dotnet-skills --skill dotnet-github-docs

安装后在 Claude Code 中输入/dotnet-github-docs确认已加载。

详细介绍

dotnet-github-docs

面向 .NET 项目的 GitHub 原生文档模式：包含 NuGet/CI/覆盖率徽章和安装说明的 README 结构、采用 Fork-PR 工作流和开发环境设置的 CONTRIBUTING.md、问题模板（包含 .NET 版本和复现步骤的错误报告，以及包含问题/解决方案/替代方案的功能请求）、包含测试检查清单和破坏性变更部分的 PR 模板、文档网站的 GitHub Pages 设置、仓库元数据（CODEOWNERS、FUNDING.yml、社交预览图、主题/标签），以及在 README 文件中嵌入 Mermaid 图表。

**版本假设：**代码示例以 .NET 8.0+ 为基准。CI 徽章使用 GitHub Actions。软件包徽章使用 NuGet.org。

**范围边界：**此技能负责 .NET 项目的 GitHub 原生文档结构和模板——即存放在仓库根目录和 .github/ 目录中的文件。GitHub Pages 网站的 CI/CD 部署流水线由 [skill:dotnet-gha-deploy] 负责。变更日志生成和版本管理约定由 [skill:dotnet-release-management] 负责。文档工具选择（Starlight、Docusaurus、DocFX）由 [skill:dotnet-documentation-strategy] 负责。Mermaid 图表语法和 .NET 专用图表模式由 [skill:dotnet-mermaid-diagrams] 负责。

**范围之外：**GitHub Pages 或文档网站的 CI/CD 部署工作流——参见 [skill:dotnet-gha-deploy]。变更日志生成和发布版本管理——参见 [skill:dotnet-release-management]。文档平台选择和配置——参见 [skill:dotnet-documentation-strategy]。Mermaid 图表语法详情——参见 [skill:dotnet-mermaid-diagrams]。项目文件结构和解决方案组织——参见 [skill:dotnet-project-structure]。

交叉引用：[skill:dotnet-gha-deploy] 介绍 GitHub Pages 部署流水线，[skill:dotnet-release-management] 介绍变更日志格式和版本管理，[skill:dotnet-mermaid-diagrams] 介绍 README 中 .NET 专用的 Mermaid 图表，[skill:dotnet-project-structure] 介绍项目元数据背景，[skill:dotnet-documentation-strategy] 介绍文档平台选择。

.NET 项目的 README 结构

结构完善的 README 能让贡献者和 .NET 项目的使用者迅速了解项目。

徽章

将徽章放在 README 顶部，并按类别分组：

# My.Library

[![NuGet](https://img.shields.io/nuget/v/My.Library.svg)](https://www.nuget.org/packages/My.Library)
[![NuGet Downloads](https://img.shields.io/nuget/dt/My.Library.svg)](https://www.nuget.org/packages/My.Library)
[![Build Status](https://github.com/mycompany/my-library/actions/workflows/ci.yml/badge.svg)](https://github.com/mycompany/my-library/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mycompany/my-library/branch/main/graph/badge.svg)](https://codecov.io/gh/mycompany/my-library)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

.NET 项目的徽章类别：

徽章来源说明
NuGet 版本shields.io + nuget.org使用软件包 ID，而非程序集名称
NuGet 下载量shields.io + nuget.org展示采用情况；总下载量使用 dt
构建状态GitHub Actions链接到 CI 工作流
代码覆盖率Codecov / Coveralls需要集成 CI
许可证shields.io与仓库中的许可证一致
.NET 版本shields.io可选；展示最低支持的 TFM
推荐的 README 章节
# My.Library

[badges here]

Short one-paragraph description of what the library does and why it exists.

## Installation

```shell
dotnet add package My.Library
```

Or via PackageReference in your `.csproj`:

```xml
<PackageReference Include="My.Library" Version="1.0.0" />
```

## Quick Start

```csharp
using My.Library;

var service = new WidgetService();
var widget = await service.CreateWidgetAsync("example");
Console.WriteLine(widget.Id);
```

## Features

- Feature 1: brief description
- Feature 2: brief description
- Feature 3: brief description

## Documentation

Full documentation is available at [https://mycompany.github.io/my-library](https://mycompany.github.io/my-library).

## Architecture

[Mermaid architecture diagram -- see [skill:dotnet-mermaid-diagrams] for patterns]

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a history of changes. For changelog format conventions, see [skill:dotnet-release-management].
README 中的架构图

在 README 中直接嵌入 Mermaid 架构图，以直观展示项目结构。GitHub 可原生渲染 Mermaid 围栏代码块：

## Architecture

```mermaid
graph TB
    subgraph Client
        App["Consumer App"]
    end
    subgraph Library["My.Library"]
        API["Public API Surface"]
        Core["Core Engine"]
        Cache["In-Memory Cache"]
    end
    App --> API
    API --> Core
    Core --> Cache
```

有关 .NET 专用图表模式，包括 C4 风格架构图、API 流程时序图和领域模型类图，请参见 [skill:dotnet-mermaid-diagrams]。

CONTRIBUTING.md 模式

Fork-PR 工作流
# Contributing to My.Library

Thank you for your interest in contributing! This document provides guidelines
and instructions for contributing.

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/my-library.git`
3. Create a feature branch: `git checkout -b feature/my-feature`
4. Make your changes
5. Submit a pull request

## Development Setup

### Prerequisites

- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later
- An IDE: [Visual Studio 2022](https://visualstudio.microsoft.com/), [VS Code](https://code.visualstudio.com/) with C# Dev Kit, or [JetBrains Rider](https://www.jetbrains.com/rider/)

### Building

```shell
dotnet restore
dotnet build
运行测试
dotnet test

运行测试并生成覆盖率报告：

dotnet test --collect:"XPlat Code Coverage"
编码标准
  • 遵循 .NET 编码约定
  • 提交前使用 dotnet format 执行代码风格检查
  • 所有公共 API 都必须包含 XML 文档注释
  • 新功能必须包含单元测试

Pull Request 流程

  1. 为任何已更改的公共 API 更新文档
  2. 添加或更新测试以覆盖你的更改
  3. 确保所有测试均通过：dotnet test
  4. 确保代码编译时没有警告：dotnet build -warnaserror
  5. 在 [Unreleased] 部分下，将你的更改更新到 CHANGELOG.md
  6. 维护者将审核该 PR

报告问题


---

## Issue Templates

### Bug Report Template

```yaml
# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
description: Report a bug in the library
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thank you for reporting a bug. Please fill out the information below
        to help us diagnose and fix the issue.

  - type: textarea
    id: description
    attributes:
      label: Description
      description: A clear and concise description of the bug.
    validations:
      required: true

  - type: textarea
    id: repro-steps
    attributes:
      label: Steps to Reproduce
      description: Steps to reproduce the behavior.
      value: |
        1. Install package version X
        2. Call method Y with parameters Z
        3. Observe error
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: Expected Behavior
      description: What you expected to happen.
    validations:
      required: true

  - type: textarea
    id: actual
    attributes:
      label: Actual Behavior
      description: What actually happened. Include any error messages or stack traces.
    validations:
      required: true

  - type: input
    id: dotnet-version
    attributes:
      label: .NET Version
      description: "Output of `dotnet --version`"
      placeholder: "8.0.100"
    validations:
      required: true

  - type: dropdown
    id: os
    attributes:
      label: Operating System
      options:
        - Windows
        - macOS
        - Linux
    validations:
      required: true

  - type: textarea
    id: additional
    attributes:
      label: Additional Context
      description: Any other context about the problem (project type, related packages, etc.)
Feature Request 模板
# .github/ISSUE_TEMPLATE/feature_request.yml
name: Feature Request
description: Suggest a new feature or enhancement
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: Problem Statement
      description: Describe the problem this feature would solve.
      placeholder: "I'm always frustrated when..."
    validations:
      required: true

  - type: textarea
    id: solution
    attributes:
      label: Proposed Solution
      description: Describe the solution you'd like to see.
    validations:
      required: true

  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives Considered
      description: Describe any alternative solutions or features you've considered.

  - type: textarea
    id: api-surface
    attributes:
      label: API Surface (if applicable)
      description: |
        If you have a proposed API design, include it here.
      render: csharp
Question / Discussion 模板
# .github/ISSUE_TEMPLATE/question.yml
name: Question
description: Ask a question about using the library
title: "[Question]: "
labels: ["question"]
body:
  - type: textarea
    id: question
    attributes:
      label: Question
      description: What would you like to know?
    validations:
      required: true

  - type: textarea
    id: context
    attributes:
      label: Context
      description: |
        Provide context about what you're trying to accomplish.
        Include code snippets if relevant.
      render: csharp
Issue 模板配置
# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: Discussions
    url: https://github.com/mycompany/my-library/discussions
    about: Use discussions for general questions and community support
  - name: Stack Overflow
    url: https://stackoverflow.com/questions/tagged/my-library
    about: Search for existing answers on Stack Overflow

PR 模板

Pull Request 模板


## Description



## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Performance improvement

## Testing Checklist

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated (if applicable)
- [ ] All existing tests pass (`dotnet test`)
- [ ] Code compiles without warnings (`dotnet build -warnaserror`)

## Breaking Changes



N/A

## Related Issues



## Additional Notes

GitHub Pages 设置

GitHub Pages 可托管由 Starlight、Docusaurus 或 DocFX 生成的文档站点。本节介绍仓库配置；CI 部署流水线配置请参阅 [skill:dotnet-gha-deploy]。

仓库设置
  1. 前往 Settings > Pages
  2. 在 Source 下，选择 GitHub Actions（不要选择旧版的基于分支的部署方式）
  3. .github/workflows/ 中的部署工作流负责构建和发布步骤
文档站点目录结构

将文档源文件放在仓库根目录下的 docs/ 目录中：

my-library/
  src/
    MyLibrary/
      MyLibrary.csproj
  docs/
    astro.config.mjs          # For Starlight
    # OR docusaurus.config.js  # For Docusaurus
    # OR docfx.json            # For DocFX
  .github/
    workflows/
      deploy-docs.yml          # Deployment workflow -- see [skill:dotnet-gha-deploy]
  README.md
  CONTRIBUTING.md
自定义域名

为 GitHub Pages 配置自定义域名：

  1. 在文档站点的静态目录中添加 CNAME 文件（例如，Starlight 使用 docs/public/CNAME，Docusaurus 使用 docs/static/CNAME）
  2. 在 Settings > Pages > Custom domain 中设置域名
  3. 启用 Enforce HTTPS

CNAME 文件中的内容：

docs.mylibrary.dev

有关文档平台的选择和配置，请参阅 [skill:dotnet-documentation-strategy]。有关部署工作流 YAML，请参阅 [skill:dotnet-gha-deploy]。

仓库元数据

CODEOWNERS

定义代码所有权，以便自动分配审核人员：

# .github/CODEOWNERS

# Default owner for everything
* @mycompany/core-team

# Documentation
/docs/ @mycompany/docs-team
*.md @mycompany/docs-team

# Source code by area
/src/MyLibrary.Core/ @mycompany/core-team
/src/MyLibrary.Data/ @mycompany/data-team

# Build and CI
/.github/ @mycompany/devops-team
/build/ @mycompany/devops-team
*.props @mycompany/core-team
*.targets @mycompany/core-team

# NuGet configuration
nuget.config @mycompany/core-team
Directory.Packages.props @mycompany/core-team
FUNDING.yml

配置 GitHub Sponsors 和其他赞助链接：

# .github/FUNDING.yml
github: [maintainer-username]
open_collective: my-library
custom: ["https://www.buymeacoffee.com/maintainer"]
社交预览图
  • 前往 Settings > General > Social preview
  • 上传一张 1280x640 的图片（宽高比为 2:1）
  • 图片应包含：项目名称、徽标、简短标语和 .NET 版本徽章
  • 使用统一的品牌配色方案
主题和标签

添加仓库主题以便于发现：

  • dotnet、csharp、nuget —— 生态系统标签
  • library、sdk、framework —— 项目类型
  • aspnetcore、efcore、blazor —— 特定技术标签
  • 描述性标签：serialization、logging、dependency-injection 等

可在 Settings > General > Topics 中设置主题，也可以在主页上的仓库描述区域进行设置。

仓库描述

仓库描述应简洁（少于 350 个字符），并包含：

  • 项目的功能
  • 主要差异化特点或主要使用场景
  • 相关时注明目标 .NET 版本

示例：“适用于 .NET 8 及更高版本的高性能 JSON 序列化库，支持源代码生成器并兼容 AOT。”

Agent 注意事项

  1. 始终使用基于 YAML 的问题模板（.yml），而不是 Markdown 模板（.md） —— YAML 模板提供带验证、下拉选项和必填字段的结构化表单。Markdown 模板是旧格式，不提供输入验证。

  2. .github/ISSUE_TEMPLATE/ 目录必须包含 config.yml —— 否则默认会显示“空白问题”选项。将 blank_issues_enabled: false 设为禁用，以强制用户使用模板。

  3. 徽章 URL 必须使用正确的 NuGet 包 ID —— 包 ID 在 shields.io 上区分大小写。请使用 NuGet.org 上的准确 ID（例如，Newtonsoft.Json，而不是 newtonsoft.json）。

  4. CODEOWNERS 模式遵循 .gitignore 语法 —— 根目录相对路径请使用 /src/。如果省略开头的 /，该模式会匹配目录树中的任意位置。

  5. GitHub Pages 源必须设为“GitHub Actions” —— 旧版“从分支部署”模式不支持自定义构建步骤。GitHub Actions 源会将构建和部署交由工作流处理。工作流 YAML 请参阅 [skill:dotnet-gha-deploy]。

  6. 不要在此技能中生成 CI/CD 部署 YAML —— GitHub Pages 的部署工作流属于 [skill:dotnet-gha-deploy]。此技能仅涵盖仓库结构和模板内容。

  7. 不要生成变更日志内容 —— 变更日志格式、版本控制策略和发行说明属于 [skill:dotnet-release-management]。请在 README 中引用 CHANGELOG.md，但不要在此处定义其格式。

  8. PR 模板文件必须准确命名为 pull_request_template.md —— GitHub 只识别此准确文件名（不区分大小写）。文件可以位于根目录、docs/ 或 .github/ 目录中。为与问题模板保持一致，建议放在 .github/ 目录中。

  9. 在 Bug 报告模板中加入 .NET Version —— .NET 版本对于复现 Bug 至关重要。预期格式请使用 dotnet --version 的输出。请将操作系统设为下拉选项，因为行为通常会因平台而异。

  10. README 中的 Mermaid 图表可由 GitHub 原生渲染 —— 无需特殊配置。请使用带有 mermaid 语言标识符的标准围栏代码块。有关可嵌入架构章节的 .NET 专用图表模式，请参阅 [skill:dotnet-mermaid-diagrams]。

评论

支持 Markdown