@ appnest/ readme (帮助)

根据您的仓库内容自动生成一个美丽的最佳操作 README 文件
_{使用这个读取器 很容易生成美丽的读取器像这个! 仅仅延长你的 package.json 并创建一个读取我的蓝图。 在Github上,README文件就像您网站的登陆页,因为它是访问者首先看到的. 汝欲作好一观.}

• 简单:使用极其简单——如此简单,几乎感觉像魔法!
• 强大的: 自定义几乎所有东西 - 如果您愿意,请添加自己的模板和变量
• 厉害: 在您拥有许多不同的存储器之前, 您不知道您需要的工具

* 安装

npm install @appnest/readme -D

如果你不想安装任何东西,你可以使用 npx @appnest/readme generate 改为命令.

QQ 开始( 快)

这个开始的向导是超快的! 跟着这两步走 你就会把无聊的读取器变成一个漂亮的读取器.

1. 重命名当前 README.md 文件为 blueprint.md。 。 。 .
2. 运行 npx @appnest/readme generate

就这样! 检查您的新生成 README.md 享受你刚刚所做的一切.

QQ 开始( 较慢)

这个开始的指南要长一点, 但会给你一些超能力。 花一分钟看这个开始的指南 你很快就会有你镇上最好的README文件了.

蓝图

首先,你需要创建一个 blueprint.md 文档。 这份蓝图将成为 README.md 我们稍后会生成文件.

让我们开始简单。 为了从你的 package.json 输入到 README 文件的文件, 我们使用胡子语法({{ .. }}) (中文(简体) ). 这么说吧 package.json 这样的文件 :

{
  "name": "@appnest/readme",
  "version": "1.2.5"
}

为了得到 name 财务报告和审定财务报表 version 输入您需要写入的 README 文件 {{ pkg.name }} 财务报告和审定财务报表 {{ pkg.version }} 在你身边 blueprint.md 这样的文件 :

Welcome to {{ pkg.name }}. This is version {{ pkg.version }}!

运行时 node_modules/.bin/readme generate 文件 README.md 将生成以下内容:

Welcome to @appnest/readme. This is version 1.2.5.

使用量

运行 node_modules/.bin/readme generate 命令和 README 文件将会为您生成。 如果您想要使用 readme 命令深入, 请检查以下选项或写入 node_modules/.bin/readme generate -h 在你的终端 如果这是你的茶.

配置

要配置此库, 您需要创建一个 blueprint.json 文档。 这个文件是我们将在下一节查看的模板的配置 。 如果您想要将配置文件的值插入到您的 README 文件, 您可以在不设范围的情况下直接引用它们 。 例如,如果你的字段"链接" blueprint.json 你可以写 {{ link }} 参考它.

伟大的。 现在我们有基本内容了, 让我们继续,看看如何使用模板!

QQ 模板

如果你走这么远,你可能有兴趣 找出如何使用 README 模板。 这个库有一套预定义的模板 让你的读取能力很棒 但你当然可以自己创建 以后再说,我们先别太过份了.

标题

从标题模板开始. 要生成您写的标题 {{ template:title }} 在你的蓝图。 当你运行 readme 命令模板将生成以下内容:

@ appnest/ readme (帮助)

这里需要注意的一点是,模板自动读取您的 package.json 文件并插入 name 从包裹.

{
  "name": "@appnest/readme"
}

这很酷。 让我们看看一些其他的内置模板 你可能想要添加.

标记

标志模板为您的读取器添加了一个标志, 看起来像这样:

使用占位符 {{ template:logo }} 盖上它。 您需要添加 logo 字段为 blueprint.json。标志字段需要 src 字段。 您可以选择为 width, (中文(简体) ), height 财务报告和审定财务报表 alt。下面是一个如何为标识模板添加数据的例子.

{
  "logo": {
    "src": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/logo-shadow.png",
    "width": "150"
  }
}

标签

徽章模板在读取器中添加了徽章,看起来是这样:

使用 {{ template:badges }} 占位符盖上它。 您需要添加有关如何生成徽章的数据 。 为此,你可以延长 ids 属性 blueprint.json 并添加 npm 财务报告和审定财务报表 github ids(两者均为可选). 如果你想加入自己的徽章,你可以使用 badges 字段.

{
  "ids": {
    "github": "andreasbm/readme",
    "npm": "@appnest/readme"
  },
  "badges": [
    {
      "alt": "Custom badge",
      "url": "https://github.com/badges/shields",
      "img": "https://img.shields.io/badge/custom-badge-f39f37.svg"
    }
  ]
}

如果你需要警徽的灵感 请检查 这个网站 出来.

说明

描述模板在读取器中添加了描述,看起来是这样:

根据您的仓库内容自动生成一个美丽的最佳操作 README 文件
_{使用这个读取器 很容易生成美丽的读取器像这个! 仅仅延长你的 package.json 并创建一个读取我的蓝图。 在Github上,README文件就像您网站的登陆页,因为它是访问者首先看到的. 汝欲作好一观.}

使用 {{ template:description }} 占位符盖上它。 要使用此模板, 您需要添加字段 description 给您的 package.json 文档。 也可以选择添加字段 text 财务报告和审定财务报表 demo 在你身边 blueprint.json 文档,将在下面描述.

// 软件包.json

{
  "description": "Automatically generate a beautiful best-practice README file based on the contents of your repository"
}

//蓝图.json

{
  "text": "Use this readme generator to easily generate beautiful readme's like this one! Simply extend your <code>package.json</code> and create a readme blueprint. On Github, the README file is like the landing page of your website because it is the first thing visitors see. You want to make a good first impression."
}

目录

内容表模板增加了目录,看起来是这样:

目录

• 目录
• * 安装
• QQ 开始( 快)
• QQ 开始( 较慢)
  • 蓝图
  • 使用量
  • 配置
• QQ 模板
  • 标题
  • 标记
  • 标签
  • 说明
  • 目录
  • 贡献者
• • 贡献者
  • 许可证
• 许可证
• 装入下标记文件
• 自动文档
• 我的按钮
  • 属性
  • 槽数
• 有点关于这个读取我
• QQ 自定义模板
• 高级!
  • 检查断开的链接
  • 新建模板语法
  • 变量
    • 对象
    • 1D 阵列
    • 二维阵列
  • 不同颜色的行
  • 格式不同的标题
• * 专题研究
• * 未来工作
• 问 题
  • 我能看看我的读取器文件会怎么看吗?
  • 我怎么能参与进来?
  • 我已经有一大堆README文件了 我没有时间改写所有文件!
  • 我能支持你吗?
• • 贡献者
• 许可证

使用 {{ template:toc }} 占位符盖上它。 科学证明这个模板会节省你生命中大约392.3小时. 说真的.

贡献者

撰稿人模板增加了撰稿人名单,看起来是这样:

• 贡献者

安德烈亚斯·梅尔森	你吗?
🔥

使用 {{ template:contributors }} 占位符盖上它。 让我们来sa 要使用这个模板 您需要添加 contributors 数组到您的 package.json 像这样的文件。 只有 name 字段.

{
  "contributors": [
    {
      "name": "Andreas Mehlsen",
      "email": "[email protected]",
      "url": "https://twitter.com/andreasmehlsen",
      "img": "https://avatars1.githubusercontent.com/u/6267397?s=460&v=4",
      "info": [
        "🔥"
      ]
    },
    {
      "name": "You?",
      "img": "https://joeschmoe.io/api/v1/random",
      "url": "https://github.com/andreasbm/readme/blob/master/CONTRIBUTING.md"
    }
  ]
}

注意到 info 阵列。 这个真的很刺激! 您可以在此添加描述贡献者的行 -- -- 例如成就的作用。 来看看 这里 对于您可以输入信息阵列的更多启发.

许可证

许可证模板增加了许可证栏目

许可证

许可证根据 麻省理工学院。 。 。 .

使用 {{ template:license }} 占位符盖上它。 要使用此模板, 您需要添加 license 字段为 package.json 像这样的文件.

{
  "license": "license"
}

装入下标记文件

你说什么? 你说得对。 可以将您读取的内容分成多个不同的文件来方便您的生活. 假设你有个档案 my-section.md为了盖上它,你需要添加 {{ load:my-section.md }}。 。 。 .

自动文档

欢迎来到未来。 来了 网络组件的自动文档!。让我们假设,在一个名为 my-button.js。 。 。 .

/**
 * Button used for clicking!
 * @slot - Default content
 */
export class MyButton extends HTMLElement {

  /**
   * Attributes being observed.
   * @returns {string[]}
   */
  static get observedAttributes() {
    return ["disabled", "role"];
  }
  
  /**
   * Disables the element.
   * @attr
   * @type {boolean}
   */
  disabled = false;

  /**
   * Role of the element.
   * @attr
   * @type {string}
   */
  role = "button";
}

customElements.define("my-button", MyButton);

然后只需写就可以为网页组件获得自动文档 {{ doc:my-button.js }} 这将产生以下内容.

我的按钮

点击时用的按钮 !

属性

槽数

如果您想要进一步了解文档是如何生成的, 请查看 web-component-analyzer。 。 。 .

有点关于这个读取我

你现在大概很想知道这个 README 文件是如何生成的? 它是从以下几个方面创建的: blueprint.md 文档.

{{ template:logo }}
{{ template:title }}
{{ template:badges }}
{{ template:description }}
{{ bullets }}
{{ template:toc }}
{{ load:readme/1-installation.md }}
{{ load:readme/2-getting-started.md }}
{{ load:readme/3-templates.md }}
{{ load:readme/4-load-markdown.md }}
{{ load:readme/5-automatic-documentation.md }}
{{ load:readme/6-this-readme.md }}
{{ load:readme/7-custom-templates.md }}
{{ load:readme/8-advanced.md }}
{{ load:readme/9-featured-readmes.md }}
{{ load:readme/10-future-work.md }}
{{ load:readme/11-faq.md }}
{{ template:contributors }}
{{ template:license }}

事情再简单不过了.

QQ 自定义模板

您可以创建自己的模板, 将事物保留为热夏日的 DRY 。 要创建自己的模板,你首先需要添加 templates 数组到您的 blueprint.json 像这样的文件.

{
  "templates": [
    {
      "name": "install",
      "template": "Run `npm install {{ ids.npm }} to install this library!"
    }
  ]
}

然后可以使用 {{ template:install }} 语法("Install"在此引用自定义模板的名称). 下面是使用上述模板被印入README文件的例子.

运行“ npm 安装@ appnest/ readme ” 以安装此库 !

要有创意! 例如,您可以为代码片段添加模板或 拼写错误。 。 。 .

高级!

瓳 你准备好打开潘多拉的盒子了吗? 贡举志五种 上.

检查断开的链接

添加数据 checkLinks 字段为 blueprint.json 并会通知所有中断的链接 在你的README文件中。 此检查使用 检查链接 检查链接的活性.

{
  "checkLinks": true
}

新建模板语法

如果您心情好, 您可以更改用于匹配模板的语法 。 不如说你想让你的占位符 换成这样 {[ template:title }]。然后你需要添加 placeholder 数组到您的 blueprint.json 新语法的文件 ["{[", "}]"] 像这样.

{
  "placeholder": ["{[", "}]"]
}

变量

如果你有一个变量 从你的 blueprint.json 您想要将文件印入您的 README 文件的文件 {{ ... }} 语法照常,没有任何范围.

对象

对象格式化为列表,按键为粗体。 如果您想盖章的话 dependencies 从字段 package.json 您写入的文件 {{ pkg.dependencies }} 依附者们将像这样被封印.

• @ types/ glob页:1
• 检查链接编号: ^ 1.1.8
• 颜色: ^1.4.0
• 指挥官: ^ 5.0
• 超时: ^ 9.0.0 (中文(简体) )
• 阴影: ^7.1.6 (中文(简体) )
• 路径页:1
• 网络组件分析器: 1.0.3 (中文(简体) )

1D 阵列

如果您有一个 1D 阵列, 它将被格式化为列表 。 如果您想盖章的话 keywords 从字段 package.json 您写入的文件 {{ pkg.keywords }} 关键词会以这样漂亮的格式被盖上:

• 开源
• 项目
• 读取我
• 模板
• 锅炉板
• 节点
• 维持
• 发电机

二维阵列

如果有一个2D阵列,它将被格式化为表格。 这对API的文档等事物来说非常方便. 这么说吧,你有以下的 blueprint.json。 。 。 .

{
  "properties": [
    ["Attribute", "Type", "Description"],
    ["**size**", "'medium', 'large'", "Determines the size" ],
    ["**active**", "boolean", "Whether the element is active or not" ]
  ]
}

然后用笔迹印在读本上 {{ properties }} 它将变成一个表格.

别客气!

不同颜色的行

如果您想要改变标题上行的颜色, 您可以更改 line 区域 blueprint.json。这里有一个例子,如果您想要一条暗线,而不是彩色线.

{
  "line": "dark"
}

以下为线条的暗变种.

对! 您的黑暗模式 README.md 确实是真棒。 除了黑暗模式,你还有其他选择。 以下是您可以选择的所有行样式.

• "水叮当"
• "可爱"
• "有颜色"
• "切"(切)
• "黑暗"(暗语)
• "火"(火)
• "草"(草)
• "大脑"
• "孤独"
• "战斗"
• "水"

如果你想要自己的线条设计,你可以给 line 将 URL 输入图像。 建议此图像为宽度为900px. 如果你喜欢没有线 你可以给 line 字串“无”.

格式不同的标题

如果您想要更改标题前面的前缀, 您可以更改 headingPrefix 输入 blueprint.json 文档。 只需将标题级别映射到以下想要的前缀 .

{
  "headingPrefix": {
    "1": "➜ ",
    "2": "⭑ "
  }
}

如果您想要一些符号的灵感, 您可以在标题前放置, 请检查 这个 网站.

* 专题研究

如果你用这台发电机来做一个项目 我很想听听,这样我就能把它弄出来 以下是一些使用此生成器的寄存器用于其README文件的列表.

• 点数翻译
• 砖瓦铺设
• 焦点陷阱
• 网络路由器
• 网络配置
• ts-lit-插孔
• 块

作为生成的README文件的布局的灵感,我最初从中找到了灵感 terkelg 的辉煌的寄存器叫做 提示 - 说明每个读取器文件应该怎么看! 因此我想在这里提及他,尽管他没有使用这个README发电机. 如果你想看到一个出色的 README 文件的例子, 你一定要检查他的仓库.

* 未来工作

就这样了! 洛特的退出特性 未来将添加。 如果你碰巧遇到问题或有特征请求,欢迎您打开 Github 问题或拉请求。 祝你今天过得愉快!

问 题

我能看看我的读取器文件会怎么看吗?

是的,你绝对可以! 有很多工具 在那里编辑/审查 Github 口味的标记下。 我建议使用 https://stackedit.io/app (英语) 以预览最终结果,因为它是超轻量级的,而且效果良好.

我怎么能参与进来?

创建一个问题或拉请求。 也欢迎你给我留言 @Andreas-Mehlsen (英语)。 。 。 .

我已经有一大堆README文件了 我没有时间改写所有文件!

没问题! 你的第一步是重新命名你 README.md 改为 blueprint.md 运行 node_modules/.bin/readme generate。那么你的读取器现在应该格式化了。 然后在有空的时候慢慢地替换内容. 低悬挂的水果将分别使用 {{ template:toc }} 财务报告和审定财务报表 {{ template:license }} 模板.

我能支持你吗?

有很多办法可以支持我! 如果你给这个寄存处一个明星

• 贡献者

安德烈亚斯·梅尔森	你吗?
🔥

许可证

许可证根据 麻省理工学院。 。 。 .