{"id":20616989,"url":"https://github.com/jungomi/mdn_query","last_synced_at":"2025-04-15T08:41:24.832Z","repository":{"id":56883106,"uuid":"71189575","full_name":"jungomi/mdn_query","owner":"jungomi","description":"Query the Mozilla Developer Network documentation","archived":false,"fork":false,"pushed_at":"2017-05-19T13:52:48.000Z","size":201,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-25T16:20:56.099Z","etag":null,"topics":["cli","docs","mdn","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/jungomi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-17T23:25:00.000Z","updated_at":"2022-02-03T00:43:34.000Z","dependencies_parsed_at":"2022-08-20T13:10:43.214Z","dependency_job_id":null,"html_url":"https://github.com/jungomi/mdn_query","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/jungomi%2Fmdn_query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jungomi%2Fmdn_query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jungomi%2Fmdn_query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jungomi%2Fmdn_query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jungomi","download_url":"https://codeload.github.com/jungomi/mdn_query/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249038887,"owners_count":21202803,"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":["cli","docs","mdn","ruby"],"created_at":"2024-11-16T11:21:29.278Z","updated_at":"2025-04-15T08:41:24.810Z","avatar_url":"https://github.com/jungomi.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MdnQuery\n\n[![Gem Version][gem-badge]][gem]\n[![Build Status][travis-img]][travis]\n[![Code Climate][codeclimate-badge]][codeclimate]\n[![Test Coverage][coverage-badge]][coverage]\n\nQuery the [Mozilla Developer Network][mdn] documentation. Unfortunately they do\nnot provide an API to fetch the documentation entries, which means that all\ninformations are extracted from the HTML pages to create a Markdown-like\nrepresentation. Another drawback is that it requires two network requests to\nretrieve a single entry based on a search term, which is frequently desired as\na precise search term almost always yields the concrete entry as the first\nresult.\n\n[Documentation][docs]\n\n## CLI\n\nThe binary `mdn-query` provides an interactive command line interface to easily\nsearch a query. By default it only searches for results in the JavaScript topic.\n\n```\nUsage: mdn-query [options] \u003csearch-term\u003e\n\nOptions:\n    -v, --version               Shows the program's version\n    -h, --help                  Shows this help message\n    -f, --first, --first-match  Returns the first match instead of a list\n    -o, --open, --open-browser  Opens the appropriate page in the default web browser\n    -t, --topics                The topics to search in, delimited by commas\n```\n\n### Examples\n\n```sh\nmdn-query bind                  # Searches for 'bind'\nmdn-query bind --first          # Retrieves first match of the search result\nmdn-query bind --open           # Opens the search results in the default browser\nmdn-query bind --first --open   # Opens the first match in the default browser\nmdn-query bind --topics js,css  # Searches in the topics 'js' and 'css'\n```\n\n### Demo\n\n![Demo][demo]\n\n## Library\n\n### Top level methods\n\nThe following methods, that each take the search query and optional search\noptions as parameters, cover the most common use cases:\n\n#### MdnQuery.list(query, options)\n\nCreates a list with the search results. The entries in the list do not yet\ncontain the content of the corresponding documentation entries. They need to be\nfetched individually.\n\n```ruby\nlist = MdnQuery.list('bind')\n# Searches in the topics 'js' and 'css'\nlist = MdnQuery.list('bind', topics: ['js', 'css'])\n# Prints a numbered list of the search result with a small description\nputs list\n# Finds all items that include 'Object' in their title\nobject_entries = list.items.select { |e| e.title =~ /Object/ }\n```\n\n#### MdnQuery.first_match(query, options)\n\nRetrieves the content of the first entry of the search results. This requires\ntwo network requests, because it is required to first search the Mozilla\nDeveloper Network and then fetch the page of the respective entry.\n\n```ruby\ncontent = MdnQuery.first_match('bind')\n# Prints a Markdown-like representation of the entry\nputs content\n```\n\n#### MdnQuery.open_list(query, options)\n\nOpens the search query in the default web browser instead of retrieving the\nresults, therefore there is no network request made.\n\n```ruby\nMdnQuery.open_list('bind')\n```\n\n#### MdnQuery.open_first_match(query, options)\n\nOpens the first entry in the default web browser instead of fetching the\ncorresponding page. This means there is only one network request to retrieve the\nlist of search results.\n\n```ruby\nMdnQuery.open_first_match('bind')\n```\n\n### Search\n\n```ruby\n# Creates a new search that is not executed yet\nsearch = MdnQuery::Search.new('bind', topics: ['js', 'css'])\n# Opens the search results in the default web browser\nsearch.open\n# Executes the search request\nsearch.execute\n# Creates a list of the search results\nlist = search.result.to_list\n```\n\nA search result can contain multiple pages. To easily navigate through the\npages, the methods `next_page` and `previous_page` are available, that retrieve\nthe next and previous page respectively, if it exists.\n\n```ruby\n# Retrieves the next page of the search results\nsearch.next_page\n# Retrieves the previous page of the search results\nsearch.previous_page\n```\n\n### Entry\n\nThe content of an entry can be retrieved with the method `content`, which\nfetches the documentation entry once, and simply returns it on further calls.\n\n```ruby\nlist = MdnQuery.list('bind', topics: ['js', 'css'])\nentry = list.first\n# Opens the entry in the default web browser\nentry.open\n# Prints the entry's content, performing a network request\nputs entry.content\n# Prints the content again without another network request\nputs entry.content\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on [GitHub][github-repo].\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License][mit].\n\n[codeclimate]: https://codeclimate.com/github/jungomi/mdn_query\n[codeclimate-badge]: https://codeclimate.com/github/jungomi/mdn_query/badges/gpa.svg\n[coverage]: https://codeclimate.com/github/jungomi/mdn_query/coverage\n[coverage-badge]: https://codeclimate.com/github/jungomi/mdn_query/badges/coverage.svg\n[demo]: screenshots/demo.gif\n[docs]: http://www.rubydoc.info/gems/mdn_query\n[gem]: https://badge.fury.io/rb/mdn_query\n[gem-badge]: https://badge.fury.io/rb/mdn_query.svg\n[github-repo]: https://github.com/jungomi/mdn-query\n[mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript\n[mit]: http://opensource.org/licenses/MIT\n[travis]:  https://travis-ci.org/jungomi/mdn_query\n[travis-img]: https://travis-ci.org/jungomi/mdn_query.svg?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjungomi%2Fmdn_query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjungomi%2Fmdn_query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjungomi%2Fmdn_query/lists"}