{"id":18631764,"url":"https://github.com/esotericpig/yard_ghurt","last_synced_at":"2025-11-04T05:30:38.089Z","repository":{"id":56899018,"uuid":"196999071","full_name":"esotericpig/yard_ghurt","owner":"esotericpig","description":":fallen_leaf::sunrise_over_mountains::icecream: YARDoc GitHub Rake Tasks.","archived":false,"fork":false,"pushed_at":"2021-06-20T10:53:35.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-03-15T01:03:44.985Z","etag":null,"topics":["gfm","github-flavored-markdown","github-pages","rake","rake-task","ruby","yardoc"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esotericpig.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-15T12:57:41.000Z","updated_at":"2021-06-20T10:53:38.000Z","dependencies_parsed_at":"2022-08-20T18:20:32.152Z","dependency_job_id":null,"html_url":"https://github.com/esotericpig/yard_ghurt","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2Fyard_ghurt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2Fyard_ghurt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2Fyard_ghurt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esotericpig%2Fyard_ghurt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esotericpig","download_url":"https://codeload.github.com/esotericpig/yard_ghurt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239425427,"owners_count":19636346,"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":["gfm","github-flavored-markdown","github-pages","rake","rake-task","ruby","yardoc"],"created_at":"2024-11-07T05:08:32.820Z","updated_at":"2025-11-04T05:30:38.041Z","avatar_url":"https://github.com/esotericpig.png","language":"Ruby","readme":"# YardGhurt\n\n[![Gem Version](https://badge.fury.io/rb/yard_ghurt.svg)](https://badge.fury.io/rb/yard_ghurt)\n\n[![Documentation](https://img.shields.io/badge/doc-yard-%23A0522D.svg)](https://esotericpig.github.io/docs/yard_ghurt/yardoc/index.html)\n[![Source Code](https://img.shields.io/badge/source-github-%23211F1F.svg)](https://github.com/esotericpig/yard_ghurt)\n[![Changelog](https://img.shields.io/badge/changelog-md-%23A0522D.svg)](CHANGELOG.md)\n[![License](https://img.shields.io/github/license/esotericpig/yard_ghurt.svg)](LICENSE.txt)\n\n\u003cu\u003eYARD\u003c/u\u003eoc \u003cu\u003eG\u003c/u\u003eit\u003cu\u003eHu\u003c/u\u003eb \u003cu\u003eR\u003c/u\u003eake \u003cu\u003eT\u003c/u\u003easks\n\n- Fix GitHub Flavored Markdown files.\n- Sync YARDoc to a local GitHub Pages repo.\n\n## Contents\n\n- [Setup](#setup)\n- [Using](#using)\n    - [GFMFixTask](#gfmfixtask)\n    - [GHPSyncTask](#ghpsynctask)\n    - [Util / YardGhurt](#util--yardghurt)\n    - [AnchorLinks](#anchorlinks)\n- [CLI App](#cli-app)\n- [Hacking](#hacking)\n    - [Testing](#testing)\n- [Tests](#tests)\n- [License](#license)\n\n## [Setup](#contents)\n\nPick your poison...\n\nWith the RubyGems CLI package manager:\n\n`$ gem install yard_ghurt`\n\nIn your *Gemspec* (*\u0026lt;project\u0026gt;.gemspec*):\n\n```Ruby\nspec.add_development_dependency 'yard_ghurt', '~\u003e X.X.X'\n```\n\nIn your *Gemfile*:\n\n```Ruby\ngem 'yard_ghurt', '~\u003e X.X.X', :group =\u003e [:development, :test]\n# or...\ngem 'yard_ghurt', :git =\u003e 'https://github.com/esotericpig/yard_ghurt.git',\n                  :tag =\u003e 'vX.X.X', :group =\u003e [:development, :test]\n```\n\nManually:\n\n```\n$ git clone 'https://github.com/esotericpig/yard_ghurt.git'\n$ cd yard_ghurt\n$ bundle install\n$ bundle exec rake install:local\n```\n\n## [Using](#contents)\n\nCurrently, you can't use this project as a YARDoc Plugin, but planning on it for v2.0. Read the [TODO](TODO.md) for more info.\n\n**Rake Tasks:**\n\n| Task | Description |\n| --- | --- |\n| [GFMFixTask](#gfmfixtask) | Fix GitHub Flavored Markdown files |\n| [GHPSyncTask](#ghpsynctask) | Sync YARDoc to a local GitHub Pages repo. |\n\n**Helpers:**\n\n| Helper | Description |\n| --- | --- |\n| [Util / YardGhurt](#util--yardghurt) | Utility methods for tasks |\n| [AnchorLinks](#anchorlinks) | A “database” of anchor links |\n\n### [GFMFixTask](#using)\n\nFix (find \u0026 replace) text in the GitHub Flavored Markdown (GFM) files in the YARDoc directory, for differences between the two formats.\n\n**Very Important!**\n\nIn order for this to work, you must also add `redcarpet` as a dependency, per YARDoc's documentation:\n\n```Ruby\nspec.add_development_dependency 'redcarpet','~\u003e X.X' # For YARDoc Markdown (*.md)\n```\n\nElse, you'll get a bunch of `label-*` relative links.\n\nYou can set *dry_run* on the command line:\n\n`$ rake yard_gfm_fix dryrun=true`\n\n**What I typically use:**\n\n```Ruby\nYardGhurt::GFMFixTask.new() do |task|\n  task.arg_names = [:dev]\n  task.dry_run = false\n  task.fix_code_langs = true\n  task.md_files = ['index.html']\n\n  task.before = Proc.new() do |t2,args|\n    # Delete this file as it's never used (index.html is an exact copy)\n    YardGhurt.rm_exist(File.join(t2.doc_dir,'file.README.html'))\n\n    # Root dir of my GitHub Page for CSS/JS\n    ghp_root_dir = YardGhurt.to_bool(args.dev) ? '../../esotericpig.github.io' : '../../..'\n\n    t2.css_styles \u003c\u003c %Q(\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"#{ghp_root_dir}/css/prism.css\" /\u003e)\n    t2.js_scripts \u003c\u003c %Q(\u003cscript src=\"#{ghp_root_dir}/js/prism.js\"\u003e\u003c/script\u003e)\n  end\nend\n```\n\n**Using all options:**\n\n```Ruby\nYardGhurt::GFMFixTask.new(:yard_fix) do |task|\n  task.anchor_db           = {'tests' =\u003e 'Testing'} # #tests =\u003e #Testing\n  task.arg_names          \u003c\u003c :name # Custom args\n  task.css_styles         \u003c\u003c '\u003clink rel=\"stylesheet\" href=\"css/my_css.css\" /\u003e' # Inserted at \u003c/head\u003e\n  task.css_styles         \u003c\u003c '\u003cstyle\u003ebody{ background-color: linen; }\u003c/style\u003e'\n  task.custom_gsub         = Proc.new() {|line| !line.gsub!('YardGhurt','YARD GHURT!').nil?()}\n  task.custom_gsubs       \u003c\u003c [/newline/i,'Do you smell what The Rock is cooking?']\n  task.deps               \u003c\u003c :yard # Custom dependencies\n  task.description         = 'Fix it'\n  task.doc_dir             = 'doc'\n  task.dry_run             = false\n  task.exclude_code_langs  = Set['ruby']\n  task.fix_anchor_links    = true\n  task.fix_code_langs      = true\n  task.fix_file_links      = true\n  task.js_scripts         \u003c\u003c '\u003cscript src=\"js/my_js.js\"\u003e\u003c/script\u003e' # Inserted at \u003c/body\u003e\n  task.js_scripts         \u003c\u003c '\u003cscript\u003edocument.write(\"Hello World!\");\u003c/script\u003e'\n  task.md_files            = ['index.html']\n  task.verbose             = false\n\n  task.before = Proc.new() {|task,args| puts \"Hi, #{args.name}!\"}\n  task.during = Proc.new() {|task,args,file| puts \"#{args.name} can haz #{file}?\"}\n  task.after  = Proc.new() {|task,args| puts \"Goodbye, #{args.name}!\"}\nend\n```\n\n### [GHPSyncTask](#using)\n\nSync YARDoc to a local GitHub Pages repo (uses `rsync` by default).\n\n**What I typically use:**\n\n```Ruby\nYardGhurt::GHPSyncTask.new() do |task|\n  task.ghp_dir = '../esotericpig.github.io/docs/yard_ghurt/yardoc'\n  task.sync_args \u003c\u003c '--delete-after'\nend\n```\n\n**Using all options:**\n\n```Ruby\n# Execute: rake ghp_doc[false,'Ruby']\nYardGhurt::GHPSyncTask.new(:ghp_doc) do |task|\n  task.arg_names   \u003c\u003c :name                      # Custom args\n  task.deps        \u003c\u003c :yard                      # Custom dependencies\n  task.description  = 'Rsync my_doc/ to my page'\n  task.doc_dir      = 'my_doc'                   # YARDoc directory of generated files\n  task.ghp_dir      = '../dest_dir/my_page'\n  task.strict       = true                       # Fail if doc_dir doesn't exist\n  task.sync_args   \u003c\u003c '--delete-after'\n  task.sync_cmd     = '/usr/bin/rsync'\n\n  task.before = Proc.new() {|task,args| puts \"Hi, #{args.name}!\"}\n  task.after  = Proc.new() {|task,args| puts \"Goodbye, #{args.name}!\"}\nend\n```\n\n### [Util / YardGhurt](#using)\n\nUtility methods for tasks.\n\n```Ruby\nrequire 'yard_ghurt/util'\n\n# If the file exists, delete it, and if +output+ is true, log it to stdout\nYardGhurt::Util.rm_exist('doc/file.README.html')\nYardGhurt::Util.rm_exist('doc/file.README.html',false)\n\n# Convert an Object to true or false\nputs YardGhurt::Util.to_bool('true') # true\nputs YardGhurt::Util.to_bool('on')   # true\nputs YardGhurt::Util.to_bool('yes')  # true\nputs YardGhurt::Util.to_bool(nil)    # false\n```\n\nFor convenience, *Util*'s methods are also included in the top module *YardGhurt*. However, this will also include all of the Tasks and Helpers, so *Util* is preferred, unless you're already requiring *yard_ghurt*.\n\n```Ruby\nrequire 'yard_ghurt'\n\nYardGhurt.rm_exist('doc/file.README.html')\nputs YardGhurt.to_bool('true')\n```\n\n### [AnchorLinks](#using)\nA “database” of anchor links specific to GitHub Flavored Markdown (GFM) and YARDoc.\n\nYou can use this by itself to view what anchor IDs would be generated:\n\n```Ruby\nrequire 'yard_ghurt/anchor_links'\n\nal = YardGhurt::AnchorLinks.new()\n\nputs al.to_github_anchor_id('This is a test!')\nputs al.to_yard_anchor_id('This is a test!')\n\n# Output:\n# ---\n# this-is-a-test\n# This_is_a_test_\n```\n\nBe aware that YARDoc depends on a common number that will be incremented for all duplicates, while GFM's number is only local to each specific duplicate:\n\n```Ruby\nal = YardGhurt::AnchorLinks.new()\nname = 'This is a test!'\n\nputs al.to_yard_anchor_id(name)   # This_is_a_test_\nputs al.to_yard_anchor_id(name)   # This_is_a_test_\n\nputs al.to_github_anchor_id(name) # this-is-a-test\nputs al.to_github_anchor_id(name) # this-is-a-test\n\nal \u003c\u003c name # Officially add it to the database\n\n# Instead of being 0 \u0026 0, will be 0 \u0026 1 (incremented),\n#   even without being added to the database\nputs al.to_yard_anchor_id(name)   # This_is_a_test_0\nputs al.to_yard_anchor_id(name)   # This_is_a_test_1\n\nputs al.to_github_anchor_id(name) # this-is-a-test-1\nputs al.to_github_anchor_id(name) # this-is-a-test-1\n\nname = 'This is another test!'\nal \u003c\u003c name # Officially add it to the database\n\n# Instead of being 0 \u0026 1, will be 2 \u0026 3 (global increment),\n#   even without being added to the database\nputs al.to_yard_anchor_id(name)   # This_is_another_test_2\nputs al.to_yard_anchor_id(name)   # This_is_another_test_3\n\nputs al.to_github_anchor_id(name) # this-is-another-test-1\nputs al.to_github_anchor_id(name) # this-is-another-test-1\n```\n\n## [CLI App](#contents)\nA CLI app has been added for convenience for when writing your own README.\n\nOn the command line:\n```\n$ yard_ghurt -g \"What's this ID?\"\n# =\u003e whats-this-id\n\n$ yard_ghurt -y \"What's this ID?\"\n# =\u003e What_s_this_ID_\n\n$ yard_ghurt -a \"What's this ID?\"\n# =\u003e GitHub: whats-this-id\n#    YARDoc: What_s_this_ID_\n```\n\nHelp:\n```\nUsage: yard_ghurt [options]\n    -a, --anchor \u003cstring\u003e            Print GitHub \u0026 YARDoc anchor link IDs of \u003cstring\u003e\n    -g, --github \u003cstring\u003e            Print GitHub anchor link ID of \u003cstring\u003e\n    -y, --yard \u003cstring\u003e              Print YARDoc anchor link ID of \u003cstring\u003e\n    ---\n    -h, --help                       Print this help\n    -v, --version                    Print the version\n```\n\n## [Hacking](#contents)\n\n```\n$ git clone 'https://github.com/esotericpig/yard_ghurt.git'\n$ cd yard_ghurt\n$ bundle install\n$ bundle exec rake -T\n```\n\n### [Testing](#hacking)\n\nFirst, execute this:\n\n`$ bundle exec rake clobber yard yard_gfm_fix[true]`\n\nThen execute this and make sure there are no warnings and no changes:\n\n`$ bundle exec rake yard_gfm_fix[true]`\n\nIt should output this:\n\n```\n[doc/file.README.html]:\n= Nothing written (up-to-date)\n[doc/index.html]:\n= Nothing written (up-to-date)\n```\n\nThen open up **doc/index.html** and check all of  the [anchor links](#tests), [local file links](#license), etc.\n\nLastly, the 2 files should be almost identical, except for 1 line:\n\n`$ diff doc/index.html doc/file.README.html`\n\n## [Tests](#contents)\n\nThese are actual tests for this gem.\n\n- [This is Test #1](#this-is-test-1)\n- [This-is-Test-#2](#this-is-test-2)\n- [This_is_Test_#3](#this_is_test_3)\n- [\"This is Test #4\"](#this-is-test-4)\n- [\"This is Test #4\"](#this-is-test-4-1)\n- [this is test #5](#this-is-test-5)\n- [THIS IS TEST #6](#this-is-test-6)\n- [日本語？](#日本語)\n- [テスト？](#テスト)\n- [中文？](#中文)\n- [汉语？](#汉语)\n\n### [This is Test #1](#tests)\n### [This-is-Test-#2](#tests)\n### [This_is_Test_#3](#tests)\n### [\"This is Test #4\"](#tests)\n### [\"This is Test #4\"](#tests)\n### [this is test #5](#tests)\n### [THIS IS TEST #6](#tests)\n### [日本語？](#tests)\n### [テスト？](#tests)\n### [中文？](#tests)\n### [汉语？](#tests)\n\n```\nNewline\nNewline\nNewline\nNewline\nNewline\nNewline\nNewline\nNewline\nNewline\nNewline\nNewline\n```\n\n## [License](#contents)\n\n[GNU LGPL v3+](LICENSE.txt)\n\n\u003e YardGhurt (\u003chttps://github.com/esotericpig/yard_ghurt\u003e)  \n\u003e Copyright (c) 2019-2021 Jonathan Bradley Whited  \n\u003e \n\u003e YardGhurt is free software: you can redistribute it and/or modify  \n\u003e it under the terms of the GNU Lesser General Public License as published by  \n\u003e the Free Software Foundation, either version 3 of the License, or  \n\u003e (at your option) any later version.  \n\u003e \n\u003e YardGhurt is distributed in the hope that it will be useful,  \n\u003e but WITHOUT ANY WARRANTY; without even the implied warranty of  \n\u003e MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  \n\u003e GNU Lesser General Public License for more details.  \n\u003e \n\u003e You should have received a copy of the GNU Lesser General Public License  \n\u003e along with YardGhurt.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.  \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesotericpig%2Fyard_ghurt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesotericpig%2Fyard_ghurt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesotericpig%2Fyard_ghurt/lists"}