{"id":18409355,"url":"https://github.com/be-fe/unbroken-doc","last_synced_at":"2025-04-12T21:52:21.122Z","repository":{"id":57385784,"uuid":"45025282","full_name":"be-fe/unbroken-doc","owner":"be-fe","description":null,"archived":false,"fork":false,"pushed_at":"2015-10-29T02:54:42.000Z","size":156,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-12T21:52:18.401Z","etag":null,"topics":[],"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":"2015-10-27T07:55:52.000Z","updated_at":"2016-12-30T08:10:56.000Z","dependencies_parsed_at":"2022-08-29T13:42:10.010Z","dependency_job_id":null,"html_url":"https://github.com/be-fe/unbroken-doc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Funbroken-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Funbroken-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Funbroken-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-fe%2Funbroken-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/be-fe","download_url":"https://codeload.github.com/be-fe/unbroken-doc/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":[],"created_at":"2024-11-06T03:24:48.978Z","updated_at":"2025-04-12T21:52:21.099Z","avatar_url":"https://github.com/be-fe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[中文文档请看这里](./README_cn.md)\n\n# Background\n\nWriting doc is one of the headaches in many projects. Some pains include, but not limited to:\n \n* No good way to refer to a specific part of content\n* Links are vulnerable due to code refactoring\n \nThis plugin is to provide a way to easily create stable markers across your project, and make your\ndocumentation links more strong. \n\n# Installation\n\nFirst, you need to have node/npm and gulp.\n\n```\ncd MY_PROJECT\nnpm install unbroken-doc\nnpm install gulp\n```\n\nAnd then, in your `gulpfile.js`, you should specify the tasks.\nThere are two in this plugin at the moment:\n\n* doc\n* validate\n\nTherefore, you could have something like this:\n\n```\nvar gulp = require('gulp');\nvar unbrokenDoc = require('unbroken-doc');\n\nunbrokenDoc.init('my-custom-project', OPTIONS);\n\ngulp.task('doc', unbrokenDoc.tasks.doc);\ngulp.task('validate', unbrokenDoc.tasks.validate);\n\n// which defines the tasks as below\n# gulp doc\n# gulp validate\n```\n\n# How to use in your project\n\nAfter having the gulp task ready, you can `cd` to your project folder, and run `gulp doc` \n(or the task that you defined).\n\nThe process will keep watching your project, and help you parsing markers.\n\n## Add a marker\n\nAt anywhere on your project, you would simply enter something like `@@{ SOME DESCRIPTION }`\non any place of any text file. \n\nThe watcher will detect it and replace it with something like:\n```\n@{{\n@[ SOME DESCRIPTION ]{_projectkey_randomkey}\n}}@\n```\n\nNote that, if you insert the ``@@{}`` pre-marker on a file of a special type, e.g. on a js file, \nthe actual marker will also be enclosed within a multi-line comment automatically. \n```\n/*@{{\n@[  ]{_projectkey_randomkey}\n}}@*/\n```\n\n## Add a reference to a marker\n\nThat's so easy, simply copy the bit `@[ SOME DESCRIPTION ]{_projectkey_randomkey}` to anywhere that \nyou want to have the reference.\n\nIn most editor (IDE), you can simply move your cursor at the line of the marker, and press `ctrl+c`\nor `cmd+c`, this line will then be copied to your clipboard. \n\nAnd next, you just simply paste it to the place you'd like to have the reference.\n\n# Config details\n\n## unbrokenDoc.init( projectKey, options )\n\n`projectKey` is the most important information in the setting, it will determine how your marker is generated.\n\nFor more information about `options` see below.\n\n## Options of config\n\nOPTIONS is the config object, if nothing is passed into `.init()`, the default object is used.\nYou can refer to the default config object below to get more idea:\n\n```\n{   \n    // the comment syntax, so that the marker can be error-free embeded on the content\n    commentSyntax: {\n        none: {start: '', end: ''},\n        xml: {start: '\u003c!--', end: '--\u003e'},\n        java: {start: '/*', end: '*/'}\n    },\n    \n    // the file that we going to process, the comment gives the comment syntax to be used in such file type\n    fileTypes: {\n        sh: {},\n        py: {},\n\n        sql: {\n            comment: 'java'\n        },\n\n        java: {\n            comment: 'java'\n        },\n\n        js: {\n            comment: 'java'\n        },\n        json: {\n            comment: 'java'\n        },\n\n        less: {\n            comment: 'java'\n        },\n        css: {\n            comment: 'java'\n        },\n\n        jsp: {\n            comment: 'xml'\n        },\n        html: {\n            comment: 'xml'\n        },\n        xml: {\n            comment: 'xml'\n        },\n        mustache: {},\n\n        data: {},\n        properties: {},\n        md: {\n            comment: 'none'\n        },\n        txt: {\n            comment: 'none'\n        }\n    },\n    \n    // the src path to watch\n    srcPath: '.',\n    \n    // where the cache file sits\n    docCacheFolderPath: './.doc_cache/',\n    \n    // which files that we ignore. Follows are the default ignores\n    ignores: [\n        // ignore all folders that start with '.'\n        /[\\/\\\\]\\./,\n        /^\\../,\n        \n        // ignore node_modules, bower_modules, vendor, build folders\n        /([\\/\\\\]|^)node_modules[\\/\\\\]/,\n        /([\\/\\\\]|^)bower_modules[\\/\\\\]/,\n        /([\\/\\\\]|^)vendor[\\/\\\\]/,\n        /([\\/\\\\]|^)build[\\/\\\\]/,\n        \n        // ignore typical non-text files\n        /\\.(mp4|avi|mkv|rm|rmvb|mp3|wav|xls|doc|xlsx|docx|class|png|jpg|gif|rar|eot|svg|ttf|woff|woff2|swf|db|jar|iml|jpeg)$/i,\n    ],\n    \n    // you can simply specify the following ignore rule, so that they are appended to the main ignore\n    addIgnores: [\n\n    ]\n};\n```\n\nOr, you can pass in a function as the `config` in `.init(projectKey, config)`.\nThe function will have the current config as input, and should return the new config object.\n\n```\nunbrokenDoc.setup('my-project', function(config) {\n    config.srcPath = './src';\n    \n    return config;\n});\n```\n\nThe processing logic of this plugin in Chinese :\n \n@[ 程序运作逻辑 ]{_unbroken_doc_385f148fa_}","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbe-fe%2Funbroken-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbe-fe%2Funbroken-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbe-fe%2Funbroken-doc/lists"}