{"id":17656719,"url":"https://github.com/burdettelamar/markdown_helper","last_synced_at":"2025-05-07T09:27:44.549Z","repository":{"id":56882825,"uuid":"120786292","full_name":"BurdetteLamar/markdown_helper","owner":"BurdetteLamar","description":"GitHub markdown helpers.  First is file inclusion.","archived":false,"fork":false,"pushed_at":"2020-03-16T13:18:42.000Z","size":757,"stargazers_count":40,"open_issues_count":4,"forks_count":19,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-01T14:53:25.595Z","etag":null,"topics":["github","include-files","markdown","readme","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/BurdetteLamar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-08T16:25:18.000Z","updated_at":"2024-12-27T01:53:35.000Z","dependencies_parsed_at":"2022-08-20T22:31:02.037Z","dependency_job_id":null,"html_url":"https://github.com/BurdetteLamar/markdown_helper","commit_stats":null,"previous_names":["burdettelamar/markdownhelper"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurdetteLamar%2Fmarkdown_helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurdetteLamar%2Fmarkdown_helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurdetteLamar%2Fmarkdown_helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurdetteLamar%2Fmarkdown_helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BurdetteLamar","download_url":"https://codeload.github.com/BurdetteLamar/markdown_helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252850220,"owners_count":21813928,"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":["github","include-files","markdown","readme","ruby"],"created_at":"2024-10-23T14:35:43.427Z","updated_at":"2025-05-07T09:27:44.527Z","avatar_url":"https://github.com/BurdetteLamar.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- \u003e\u003e\u003e\u003e\u003e\u003e BEGIN GENERATED FILE (include): SOURCE markdown/readme/README.template.md --\u003e\n# Markdown Helper\n\n[![Gem](https://img.shields.io/gem/v/markdown_helper.svg?style=flat)](http://rubygems.org/gems/markdown_helper \"View this project in Rubygems\")\n\n## Contents\n- [Installation](#installation)\n- [What's a Markdown Helper?](#whats-a-markdown-helper)\n- [How It Works](#how-it-works)\n  - [Restriction: ```git``` Only](#restriction-git-only)\n  - [Commented or Pristine?](#commented-or-pristine)\n- [File Inclusion](#file-inclusion)\n  - [Re-use Text](#re-use-text)\n  - [Include Generated Text](#include-generated-text)\n  - [Nest Inclusions](#nest-inclusions)\n  - [Merged Text Formats](#merged-text-formats)\n    - [Markdown](#markdown)\n    - [Highlighted Code Block](#highlighted-code-block)\n    - [Plain Code Block](#plain-code-block)\n    - [Comment](#comment)\n    - [Details](#details)\n  - [Pre-Formatted Text](#pre-formatted-text)\n  - [Usage](#usage)\n    - [CLI](#cli)\n    - [API](#api)\n    - [Include Descriptions](#include-descriptions)\n      - [Example Include Descriptions](#example-include-descriptions)\n    - [Page TOC](#page-toc)\n    - [Diagnostics](#diagnostics)\n      - [\"Noisy\" (Not Pristine)](#noisy-not-pristine)\n      - [Missing Includee File](#missing-includee-file)\n      - [Circular Inclusion](#circular-inclusion)\n- [Run ```irb```](#run-irb)\n- [What Should Be Next?](#what-should-be-next)\n\n## Installation\n\n```gem install markdown_helper```\n\n## What's a Markdown Helper?\n\nClass \u003ccode\u003eMarkdownHelper\u003c/code\u003e supports:\n\n* [File inclusion](#file-inclusion): to include text from other files, as code-block or markdown.\n* [Page TOC](#page-toc): to create and insert the table of contents for a markdown page.\n* [Run irb](#run-irb): to execute Ruby snippets in the Ruby interactive shell (```irb```) and include the output in markdown.\n\n## How It Works\n\nThe markdown helper is a preprocessor that reads a markdown document (template) and writes another markdown document.\n\nThe template can contain certain instructions that call for file inclusions.\n\n### Restriction: ```git``` Only\n\nThe helper works only in a ```git``` project:  the working directory or one of ita parents must be a git directory -- one in which command ```git rev-parse --git-dir``` succeeds.\n\n### Commented or Pristine?\n\nBy default, the output markdown has added comments that show:\n\n* The path to the template file.\n* The path to each included file.\n\nYou can suppress those comments using the \u003ccode\u003epristine\u003c/code\u003e option.\n\n## File Inclusion\n\n\u003cimg src=\"images/include.png\" alt=\"include_icon\" width=\"50\"\u003e\n\nThis markdown helper enables file inclusion in GitHub markdown.\n\n(Actually, this README file itself is built using file inclusion.)\n\nSee all [use cases](markdown/use_cases/use_cases.md#use-cases).\n\n### Re-use Text\n\nKeep your markdown DRY (Don't Repeat Yourself) by re-using text.  See the [use case](markdown/use_cases/include/reuse_text/use_case.md#reuse-text).\n\n### Include Generated Text\n\nIn particular, you can include text that's built during your \"readme build.\"  See the [use case](markdown/use_cases/include/include_generated_text/use_case.md#include-generated-text).\n\n### Nest Inclusions\n\nYou can nest inclusions.  See the [use case](markdown/use_cases/include/nest_inclusions/use_case.md#nest-inclusions).\n\n### Merged Text Formats\n\n#### Markdown\n\nYou can include text that is to be treated simply as markdown.  See the [use case](markdown/use_cases/include/include_markdown/use_case.md#include-markdown).\n\n#### Highlighted Code Block\n\nYou can include a code block that's to be highlighted.  See the [use case](markdown/use_cases/include/include_highlighted_code/use_case.md#include-highlighted-code).\n\n#### Plain Code Block\n\nYou can also include a code block without highlighting.  See the [use case](markdown/use_cases/include/include_code_block/use_case.md#include-code-block).\n\n#### Comment\n\nYou can include text that's to become a comment in the markdown.  See the [use case](markdown/use_cases/include/include_text_as_comment/use_case.md#include-text-as-comment).\n\n#### Details\n\nYou can include text that's to become details in the markdown.  See the [use case](markdown/use_cases/include/include_text_as_details/use_case.md#include-text-as-details).\n\n### Pre-Formatted Text\n\nYou can include text that's pre-formatted.  See the [use case](markdown/use_cases/include/include_text_as_pre/use_case.md#include-text-as-pre).\n\n### Usage\n\n#### CLI\n\n\u003c!-- \u003e\u003e\u003e\u003e\u003e\u003e BEGIN INCLUDED FILE (code_block): SOURCE bin/usage/include.txt --\u003e\n```include.txt```:\n```\n\nUsage: markdown_helper include [options] template_file_path markdown_file_path\n        --pristine                   No comments added\n        --help                       Display help\n    \n  where\n\n    * template_file_path is the path to an existing file.\n    * markdown_file_path is the path to a file to be created.\n\n  Typically:\n\n    * Both file types are .md.\n    * The template file contains file inclusion descriptions.\n```\n\u003c!-- \u003c\u003c\u003c\u003c\u003c\u003c END INCLUDED FILE (code_block): SOURCE bin/usage/include.txt --\u003e\n\n#### API\n\n\u003c!-- \u003e\u003e\u003e\u003e\u003e\u003e BEGIN INCLUDED FILE (ruby): SOURCE markdown/readme/include_usage.rb --\u003e\n```include_usage.rb```:\n```ruby\nrequire 'markdown_helper'\n\ntemplate_file_path = 'highlight_ruby_template.md'\nmarkdown_file_path = 'highlighted_ruby.md'\n# Pristine.\nmarkdown_helper = MarkdownHelper.new\nmarkdown_helper.pristine = true\nmarkdown_helper.include(template_file_path, markdown_file_path)\n# Also pristine.\nmarkdown_helper = MarkdownHelper.new(:pristine =\u003e true)\nmarkdown_helper.include(template_file_path, markdown_file_path)\n```\n\u003c!-- \u003c\u003c\u003c\u003c\u003c\u003c END INCLUDED FILE (ruby): SOURCE markdown/readme/include_usage.rb --\u003e\n\n#### Include Descriptions\n\nSpecify each file inclusion at the beginning of a line via an *include description*, which has the form:\n\n\u003ccode\u003e@[\u003c/code\u003e*format*\u003ccode\u003e]\\(\u003c/code\u003e*relative_file_path*\u003ccode\u003e)\u003c/code\u003e\n\nwhere:\n\n* *format* (in square brackets) is one of the following:\n  * Highlighting mode such as \u003ccode\u003e[ruby]\u003c/code\u003e, to include a highlighted code block.  This can be any Ace mode mentioned in [GitHub Languages](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml).\n  * \u003ccode\u003e[:code_block]\u003c/code\u003e, to include a plain code block.\n  * \u003ccode\u003e[:markdown]\u003c/code\u003e, to include text markdown (to be rendered as markdown).\n  * \u003ccode\u003e[:comment]\u003c/code\u003e, to include text as a markdown comment.\n  * \u003ccode\u003e[:pre]\u003c/code\u003e, to include pre-formatted text.\n  * \u003ccode\u003e[:details]\u003c/code\u003e, to include text as details.\n* *relative_file_path* points to the file to be included.\n\n##### Example Include Descriptions\n\n\u003c!-- \u003e\u003e\u003e\u003e\u003e\u003e BEGIN INCLUDED FILE (code_block): SOURCE markdown/readme/include.md --\u003e\n```include.md```:\n```\n@[ruby](my_ruby.rb)\n\n@[:code_block](my_language.xyzzy)\n\n@[:markdown](my_markdown.md)\n\n@[:comment](my_comment.txt)\n\n@[:pre](my_preformatted.txt)\n```\n\u003c!-- \u003c\u003c\u003c\u003c\u003c\u003c END INCLUDED FILE (code_block): SOURCE markdown/readme/include.md --\u003e\n\n#### Page TOC\n\nYou can specify the location for an automatically-generated page TOC (table of cotents).  See the [use case](markdown/use_cases/include/include_page_toc/use_case.md#include-page-toc).\n\n#### Diagnostics\n\n##### \"Noisy\" (Not Pristine)\n\nBy default, the markdown helper inserts comments indicating inclusions.  See the [use case](markdown/use_cases/include/include_with_added_comments/use_case.md#include-with-added-comments).\n\n##### Missing Includee File\n\nA missing includee file causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include/diagnose_missing_includee/use_case.md#diagnose-missing-includee).\n\n##### Circular Inclusion\n\nA circular inclusion causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include/diagnose_circular_includes/use_case.md#diagnose-circular-includes).\n\n## Run ```irb```\n\n* Execute Ruby snippets in the Ruby interactive shell (```irb```) and include the output in markdown.  See the [use case](markdown/use_cases/run_irb/run_irb/use_case.md#run-irb).\n\n## What Should Be Next?\n\nI have opened some enhancement Issues in the GitHub [markdown_helper](https://github.com/BurdetteLamar/markdown_helper) project:\n\n* [Project TOC](https://github.com/BurdetteLamar/markdown_helper/issues/37):  table of contents of all markdown pages in project.\n* [Partial file inclusion](https://github.com/BurdetteLamar/markdown_helper/issues/38):  including only specified lines from a file (instead of the whole file).\n* [Ruby-entity inclusion](https://github.com/BurdetteLamar/markdown_helper/issues/39):  like file inclusion, but including a Ruby class, module, or method.\n* [Pagination](https://github.com/BurdetteLamar/markdown_helper/issues/40):  series of markdown pages connected by prev/next navigation links.\n\nFeel free to comment on any of these, or to add more Issues (enhancement or otherwise).\n\u003c!-- \u003c\u003c\u003c\u003c\u003c\u003c END GENERATED FILE (include): SOURCE markdown/readme/README.template.md --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburdettelamar%2Fmarkdown_helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fburdettelamar%2Fmarkdown_helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburdettelamar%2Fmarkdown_helper/lists"}