{"id":19599039,"url":"https://github.com/mrcheater/mdis","last_synced_at":"2025-04-27T16:32:03.613Z","repository":{"id":45068269,"uuid":"165377670","full_name":"MrCheater/mdis","owner":"MrCheater","description":"Markdown include source","archived":false,"fork":false,"pushed_at":"2024-04-06T06:03:41.000Z","size":129,"stargazers_count":24,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T08:46:19.574Z","etag":null,"topics":["embed","embedded","javascript","markdown","npm","utils"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MrCheater.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-12T11:01:02.000Z","updated_at":"2024-04-05T13:01:59.000Z","dependencies_parsed_at":"2024-04-04T04:26:44.052Z","dependency_job_id":"b3aaeef6-3970-446b-9025-a598fabf2b2b","html_url":"https://github.com/MrCheater/mdis","commit_stats":{"total_commits":25,"total_committers":3,"mean_commits":8.333333333333334,"dds":0.48,"last_synced_commit":"72915241a016c0ffea849cdf86f0a46dc6581b0c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrCheater%2Fmdis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrCheater%2Fmdis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrCheater%2Fmdis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrCheater%2Fmdis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MrCheater","download_url":"https://codeload.github.com/MrCheater/mdis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251171439,"owners_count":21547112,"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":["embed","embedded","javascript","markdown","npm","utils"],"created_at":"2024-11-11T09:08:50.457Z","updated_at":"2025-04-27T16:32:03.334Z","avatar_url":"https://github.com/MrCheater.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# _mdis_: MD Source code inclusion tuner [JS, TS, etc.]\n\n_mdis_ — **M**ark**D**own **I**nclude **S**ource — provides means for precisely tuning the appearance of the JS, TS, etc. code snippets for further reference in your Mardkown-based documentation files, available for both inside and public use; with _mdis_ you will be able to embed code snippets with **specified displayed/hidden sections** and syntax highlighting support for multiple programming languages, including vanilla JavaScript and TypeScript — all in your Markdown files.\n\n\u003e ✅ **Supports** vanilla JavaScript, TypeScript, React, Node.js  \n\u003e 🔧 **Friendly** in installation and use  \n\u003e ⚡ **Lightweight and fast**\n\u003e \n\u003e ⚙️ **Code in unsupported languages** importable _as whole file's contents_, with legitimate syntax highliting (as long as your Markdown processor supports it for the given language).\n\n## _mdis_ operation and use\n### 0. Installation ⏬\n\u003e You will need to import _mdis_ separately for each of your projects. We suggest installing it as a development stage dependency:\n\u003e ```powershell\n\u003e npm install mdis --save-dev\n\u003e ```\n\u003e  \n\u003e **Now, by using `mdis-` comments _within your code_, you will be able to control some aspects of how it will be _rendered when referenced in Markdown_:**\n\n### 1. Basic visibility control with _mdis-start/mdis-stop_ comments 👁️\nWhere you want to change the visibility of sections of code when embedded in the project's .MD files, use:  \n* `mdis-start` to mark the start of the visible section, and  \n* `mdis-stop` to mark the end of such section.\n  \n### 2. Chaining of visibility declarations 🚃\nUsing several  `mdis-start`/`mdis-stop` comments in the same code file will lead to sections enclosed in such comments appearing in the .MD file, and the rest of the code being omitted, with `...` in its place _(see  [Nameless sections](#nameless-sections))_. You may not interpolate unappended `mdis-start`/`mdis-stop` sections with one another in any way; only sequential use is allowed for them.\n  \n### 3. Creating named code sections; interpolating of sections 🏷️\nYou can append your start/stop declarations with an arbitrary section name.  \n1. You must include the section name for **both starting and ending comment** of the respective section.  \n2. 🖇️ Named sections may follow one another _(see [Named sections](#named-sections))_, be nested, or overlap with one another _(see [Overlapping sections](#overlapping-sections))_.  \n3. The section names may only include **alphabetical characters in either case, numerals, dashes, and underscores** (`A..Z, a..z, 0..9, -, _`).\n4. Portions of code with named `mdis-` sections will appear in the .MD files under an *extended URL*: `[mdis]:# (./path/file.js_#section-name)` — as opposed to nameless `mdis-`-tuned portions of code: `[mdis]:# (./path/file.js)`.\n5. Portions of code with named `mdis-` sections will have a *code snippet name* set as `title=\"section-name\"`, with the exact same spelling and capitalization as given in the respective `mdis-` comments.\n\n### 4. Using _mdis_ with unsupported languages ⚙️\nIf you use _mdis_ with code in an unsupported language, you will only be able to embed the respective files' contents as a whole, with no visibility restrictions in force, regardless of whether you made the `mdis-` comments in them or not _(see [Raw import](#raw-import))_.\n\n### 5. _Actually_ referencing _mdis_-tuned code in .MD files 🔗\nTo reference `mdis-`-tuned code in your .MD files through _mdis_ import,\n\u003c!-- ❗💬 STEPS BELOW ARE MY SPECULATIONS ON HOW THIS SHOULD BE DONE; I SUPPOSE ONE WON'T WANT CODE IMPORTS INLINE, HENCE ADDING THESE \"ADD NEW LINE\" STEPS; ALSO, I'M ABSOLUTELY CONFUSED AS TO _HOW TO ACTUALLY RUN THE UTILITY ❗💬 --\u003e\n   1. Start at a new line;\n   2. Preface the MD link to the code file with `[mdis]`; then, write down the code file link like you normally would;\n   3. Add a new line;\n   4. Run _mdis_; \u003c!-- ❗💬 HOW DOES ONE DO IT ❗💬 --\u003e\n   5. After the utility is done working, your\n      ```[mdis](./path/file.ext)```\n      will turn into:\n      `````markdown\n      [mdis]#: (./path/file.ext)\n      ```lang\n      code {\n        ...\n      }\n      ```\n      `````\n      — with the code being added automatically based on the visibility flow set for the corresponding code file with the `mdis-` comments.\n  \n### 6. Specifics of code snippets render 📏\n_mdis_-processed code snippets are dependent on the respective code files: code snippets' contents **will change** if you make **changes to the referenced portions of code**, — and will *always reflect reference sources' state* upon restart, even if you try to make amendments in the rendered code snippets within the .MD file.\n  \n### 7. Export from .MD files using _mdis_-tuned code snippets ⏫\nUpon export through Markdown-to-RTF/PDF/XML/etc. processors, the .MD files including `mdis-`-tuned portions of code **will have such snippets displayed exactly as written (and tuned) in their source files**, regardless of any amendments you might make over reference copies of them in the .MD files.\n\nNow, below are examples of how `mdis-`-tuned JS code appears when referenced in an .MD file, as well as how non-supported language code gets imported when processed with _mdis_.\n\n## Examples of output from various use scenarios\n\u003e ⚠ We recommend reading the below section with this repo file tree open by the side: that way you will better understand the _**source code file** + `mdis-` comments_ ⇒ _**.MD file** + _mdis lib_ processing_ logic.\n\n### Nameless sections\n\n**📜 .JS file with `mdis-` comments**\n`````js\n// mdis-start\nclass Point {\n// mdis-stop\n  constructor(x, y) {\n    this.x = x\n    this.y = y\n  }\n// mdis-start\n}\n// mdis-stop\n\nexport default Point\n`````\n\u003e In an .MD file, `[mdis](./tests/files/simple.js)` will turn into:\n \n**🤖 .MD file after _mdis_ lib processing**\n`````markdown\n[mdis]:# (./tests/files/simple.js)\n```js\nclass Point {\n  ...\n}\n```\n`````\n  \n### Named sections\n\n**📜 .JS file with `mdis-` comments**\n`````js\n// mdis-start imports\nimport React from 'react';\n// mdis-stop imports\nclass NamedBlocks extends React.PureComponent {\n  // mdis-start render\n  render() {\n    return \u003cdiv\u003eSample\u003c/div\u003e;\n  }\n  // mdis-stop render\n}\n`````\n\u003e In an .MD file, `[mdis](./tests/files/named-blocks.js)` will turn into:\n  \n**🤖 .MD file after _mdis_ lib processing**\n`````markdown\n[mdis]:# (./tests/files/named-blocks.js#imports)\n```js title=\"imports\"\nimport React from 'react';\n```\n\n[mdis]:# (./tests/files/named-blocks.js#render)\n```js title=\"render\"\nrender() {\n  return \u003cdiv\u003eSample\u003c/div\u003e;\n}\n```\n`````\n  \n### Overlapping sections\n\n**📜 .JS file with `mdis-` comments**\n`````js\nexport default [\n  // mdis-start yellow\n  'banana',\n  // mdis-start round\n  'sun',\n  'lemon',\n  // mdis-stop yellow\n  'apple'\n  // mdis-stop round\n];\n`````\n\u003e In an .MD file, `[mdis](./tests/files/intersection.js)` will turn into:\n  \n**🤖 .MD file after _mdis_ lib processing**\n`````markdown\n[mdis]:# (./tests/files/intersection.js#round)\n```js\n'sun',\n'lemon',\n'apple'\n```\n\n[mdis]:# (./tests/files/intersection.js#yellow)\n```js\n'banana',\n'sun',\n'lemon',\n```\n`````\n  \n### Raw import\n\n**📄 ._YAML_ file with `mdis-` comments**\n`````yaml\ndocker:\n# mdis-start\n  - image: ubuntu:14.04\n# mdis-stop\n  - image: mongo:2.6.8\n    command: [mongod, --smallfiles]\n  - image: postgres:9.4.1\n`````\n\u003e In an .MD file, `[mdis](./tests/files/config.yaml)` will turn into:\n  \n**🤖 .MD file after _mdis_ lib processing**\n`````markdown\n[mdis]:# (./tests/files/config.yaml)\n```yaml\ndocker:\n# mdis-start\n  - image: ubuntu:14.04\n# mdis-stop\n  - image: mongo:2.6.8\n    command: [mongod, --smallfiles]\n  - image: postgres:9.4.1\n```\n`````\n\n\u003c!-- -=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-\n\n❌ 1. Simple block\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003cem\u003emdis\u003c/em\u003e input\u003c/th\u003e\n\u003cth\u003eResult\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003cpre\u003e\n\u003ccode markdown\u003e\n// mdis-start\nclass Point {\n// mdis-stop\n\n  constructor(x, y) {\n    this.x = x\n    this.y = y\n  }\n\n// mdis-start\n}\n// mdis-stop\n\nexport default Point\n\u003c/code\u003e\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cpre\u003e\n[mdis]:# (./tests/files/simple.js)\n```js title=\"Simple\"class Point {\n  ...\n}```\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n❌ 2. Named block\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003cem\u003emdis\u003c/em\u003e input\u003c/th\u003e\n\u003cth\u003eResult\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003cpre\u003e\n// mdis-start imports\nimport React from 'react';\n// mdis-stop imports\n\nclass NamedBlocks extends React.PureComponent {\n\u0026#160;\u0026#160;// mdis-start render\n\u0026#160;\u0026#160;render() {\n\u0026#160;\u0026#160;\u0026#160;\u0026#160;return \u0026lt;div\u0026gt;Sample\u0026lt;/div\u0026gt;;\n\u0026#160;\u0026#160;}\n\u0026#160;\u0026#160;// mdis-stop render\n}\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cpre\u003e\n[mdis]:# (./tests/files/named-blocks.js#imports)\n```\nimport React from 'react';\n```\n\u003c/pre\u003e\n\u003cpre\u003e\n[mdis]:# (./tests/named-blocks.js#render)\n```\nrender() {\n  return \u0026lt;div\u0026gt;Sample\u0026lt;/div\u0026gt;;\n}\n```\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n❌ 3. Intersection\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003cem\u003emdis\u003c/em\u003e input\u003c/th\u003e\n\u003cth\u003eResult\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003cpre\u003e\nexport default [\n  // mdis-start yellow\n  'banana',\n  // mdis-start round\n  'sun',\n  'lemon',\n  // mdis-stop yellow\n  'apple'\n  // mdis-stop round\n];\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cpre\u003e\n[mdis]:# (./tests/files/intersection.js#round)\n```js\n'sun',\n'lemon',\n'apple'\n```\n\u003c/pre\u003e\n\u003cpre\u003e\n[mdis]:# (./tests/files/intersection.js#yellow)\n```js\n'banana',\n'sun',\n'lemon',\n```\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n❌ 4. Raw\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003cem\u003emdis\u003c/em\u003e input\u003c/th\u003e\n\u003cth\u003eResult\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003cpre\u003e\ndocker:\n  - image: ubuntu:14.04\n  - image: mongo:2.6.8\n    command: [mongod, --smallfiles]\n  - image: postgres:9.4.1\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cpre\u003e\n[mdis]:# (./tests/files/config.yaml)\n```yaml\ndocker:\n  - image: ubuntu:14.04\n  - image: mongo:2.6.8\n    command: [mongod, --smallfiles]\n  - image: postgres:9.4.1\n```\n\u003c/pre\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrcheater%2Fmdis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrcheater%2Fmdis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrcheater%2Fmdis/lists"}