{"id":18409365,"url":"https://github.com/be-fe/quick-reference","last_synced_at":"2025-04-12T21:52:33.277Z","repository":{"id":57158649,"uuid":"134443702","full_name":"be-fe/quick-reference","owner":"be-fe","description":"Set link or image reference in markdown quickly and easily","archived":false,"fork":false,"pushed_at":"2018-06-08T07:19:49.000Z","size":8176,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-12T21:52:27.510Z","etag":null,"topics":["asset","image","link","markdown","reference"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/be-fe.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-22T16:28:31.000Z","updated_at":"2018-06-08T07:19:51.000Z","dependencies_parsed_at":"2022-09-07T21:01:21.465Z","dependency_job_id":null,"html_url":"https://github.com/be-fe/quick-reference","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Fquick-reference","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Fquick-reference/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Fquick-reference/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Fquick-reference/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/be-fe","download_url":"https://codeload.github.com/be-fe/quick-reference/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637833,"owners_count":21137538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asset","image","link","markdown","reference"],"created_at":"2024-11-06T03:24:52.630Z","updated_at":"2025-04-12T21:52:33.258Z","avatar_url":"https://github.com/be-fe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# quick-reference\n\n[![build status](https://img.shields.io/travis/be-fe/quick-reference/master.svg?style=flat-square)](https://travis-ci.org/be-fe/quick-reference)\n[![Test coverage](https://img.shields.io/codecov/c/github/be-fe/quick-reference.svg?style=flat-square)](https://codecov.io/github/be-fe/quick-reference?branch=master)\n[![NPM version](https://img.shields.io/npm/v/quick-reference.svg?style=flat-square)](https://www.npmjs.com/package/quick-reference)\n[![NPM Downloads](https://img.shields.io/npm/dm/quick-reference.svg?style=flat-square\u0026maxAge=43200)](https://www.npmjs.com/package/quick-reference)\n\n一种快速引用 markdown 资源（markdown、图片）的方式。\n\n## 为什么\n\n在层级深的 markdown 文档结构中，如下\n\n```markdown\ntestdocs/\n├── fsssww.md\n├── imgs/\n│ └── Edam.png\n├── index.md\n├── nodejs/\n│ ├── fs.md\n│ ├── index.md\n│ └── module.md\n├── test.md\n├── test2.md\n├── testss.md\n├── 团队项目/\n│ ├── cookbook/\n│ │ ├── cookbook-v1.md\n│ │ └── index.md\n│ └── release-scripts/\n│ └── index.md\n├── 工具链/\n│ └── docker/\n│ └── docker.md\n└── 技术栈/\n├── avalon.md\n└── avalon 监控属性的坑.md\n```\n\n我们在写一篇文章 A 的时候，想去引用（Reference）该文档中的其他文档或图片，我们需要去一层层 `../` 找到对应的目录，这样引用资源繁琐。\n\n于是便有了 `quick-reference` 的用武之地，quick-reference 主张扁平文件结构，在以上层级较深的结构中，会被扁平化为：\n\n```markdown\nfsssww\nEdam.png\nindex\nnodejs\nfs\nmodule\ntest\ntest2\ntestss\ncookbook\ncookbook-v1\nrelease-scripts\ndocker\navalon\navalon 监控属性的坑\n```\n\n我们可以用过下面的方式来指定扁平效果下的**唯一** id\n\n可以在文章头部指定 permalink:\n\n```markdown\n---\npermalink: hssss\n---\n```\n\n如果 permalink 未被指定的话，将会使用文件名作为 permalink, 如 `fs.md` 被认为是 `fs`，同时 `nodejs/index.md` 中的 `index.md` 的 permalink 会被认为为 `nodejs`。\n\n## 说明\n\n有了上面的扁平文件的概念之后，通过下面的语法\n\n    @link:premalink@  \n    @link:[title]premalink@\n    @img:premalink@\n    @img:[title]premalink@\n\n会自动转换成对应 permalink 的资源，link 转换为`[...](...)`，img 转换为`![](...)`\n\n效果如图展示：\n\n![](./snapshot.gif)\n\n## 使用\n\n    npm install quick-reference -g\n\n安装后，新增了 2 个命令 `quick-ref-watch` 和 `quick-ref`.\n\n安装后，在项目的 package.json 中配置 (使用[cosmiconfig](https://github.com/davidtheclark/cosmiconfig))\n\n    \"quick-reference\": {\n      \"docRoot\": \"path/to/docroot\"\n    }\n\n```bash\n# 开启文件监听服务，`-o` 表示覆写改动的文件，默认不开启\nquick-ref-watch -o\n\n# 同时可以不使用文件监听进程`-o`标志\n# 使用 quick-ref 进行转换亦可\nquick-ref \u003c...md files\u003e\n```\n\n## 怎么工作的？\n\n[戳这里](./Principle.md)\n\n## 推荐的使用姿势\n\n在开启了 `quick-ref-watch` 服务（不开启`-o`）后，在 IDE 中配置 `quick-ref` 进行 markdown 转换。\n\n下面介绍在不同 IDE 中 `quick-ref` 的使用方式。\n\n### WebStorm JetBrain\n\n#### 方式一 (External Tools，快捷键触发)\n\n* Preferences - External Tools\n  ![](https://i.loli.net/2018/05/24/5b06446b5a143.png)\n\n* New Tool\n  ![](https://i.loli.net/2018/06/08/5b1a2de85b74b.png)\n\n* Enable `quick-reference`, and apply the setting.\n  ![](https://i.loli.net/2018/05/24/5b06453786505.png)\n\n* Set Keymap for run `quick-reference`\n  ![](https://i.loli.net/2018/05/24/5b0645aac42c1.png)\n\n#### 方法二（File Watcher，监控文件修改自动执行）\n\n![](https://i.loli.net/2018/05/24/5b0645eea912a.png)\n\n![](https://i.loli.net/2018/05/24/5b064614d75d2.png)\n\n![](https://i.loli.net/2018/05/24/5b06464ec7909.png)\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbe-fe%2Fquick-reference","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbe-fe%2Fquick-reference","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbe-fe%2Fquick-reference/lists"}