MdnQuery
Query the Mozilla Developer Network documentation. Unfortunately they do not provide an API to fetch the documentation entries, which means that all informations are extracted from the HTML pages to create a Markdown-like representation. Another drawback is that it requires two network requests to retrieve a single entry based on a search term, which is frequently desired as a precise search term almost always yields the concrete entry as the first result.
CLI
The binary mdn-query provides an interactive command line interface to easily search a query. By default it only searches for results in the JavaScript topic.
“sage: mdn-query [options]
Maruku could not parse this XML/HTML:
<search-term>Options: -v, –version Shows the program’s version -h, –help Shows this help message -f, –first, –first-match Returns the first match instead of a list -o, –open, –open-browser Opens the appropriate page in the default web browser -t, –topics The topics to search in, delimited by commas
“
Examples
“ mdn-query bind # Searches for ‘bind’ mdn-query bind –first # Retrieves first match of the search result mdn-query bind –open # Opens the search results in the default browser mdn-query bind –first –open # Opens the first match in the default browser mdn-query bind –topics js,css # Searches in the topics ‘js’ and ‘css’
“
Demo
Library
Top level methods
The following methods, that each take the search query and optional search options as parameters, cover the most common use cases:
MdnQuery.list(query, options)
Creates a list with the search results. The entries in the list do not yet contain the content of the corresponding documentation entries. They need to be fetched individually.
“by list = MdnQuery.list(‘bind’)
Searches in the topics ‘js’ and ‘css’
list = MdnQuery.list(‘bind’, topics: [js, css])
Prints a numbered list of the search result with a small description
puts list
Finds all items that include ‘Object’ in their title
object_entries = list.items.select { |e| e.title =~ /Object/ }
“
MdnQuery.first_match(query, options)
Retrieves the content of the first entry of the search results. This requires two network requests, because it is required to first search the Mozilla Developer Network and then fetch the page of the respective entry.
“by content = MdnQuery.first_match(‘bind’)
Prints a Markdown-like representation of the entry
puts content
“
MdnQuery.open_list(query, options)
Opens the search query in the default web browser instead of retrieving the results, therefore there is no network request made.
“by MdnQuery.open_list(‘bind’)
“
MdnQuery.open_first_match(query, options)
Opens the first entry in the default web browser instead of fetching the corresponding page. This means there is only one network request to retrieve the list of search results.
“by MdnQuery.open_first_match(‘bind’)
“
Search
“by
Creates a new search that is not executed yet
search = MdnQuery::Search.new(‘bind’, topics: [js, css])
Opens the search results in the default web browser
search.open
Executes the search request
search.execute
Creates a list of the search results
list = search.result.to_list
“
A search result can contain multiple pages. To easily navigate through the pages, the methods next_page and previous_page are available, that retrieve the next and previous page respectively, if it exists.
“by
Retrieves the next page of the search results
search.next_page
Retrieves the previous page of the search results
search.previous_page
“
Entry
The content of an entry can be retrieved with the method content, which fetches the documentation entry once, and simply returns it on further calls.
“by list = MdnQuery.list(‘bind’, topics: [js, css]) entry = list.first
Opens the entry in the default web browser
entry.open
Prints the entry’s content, performing a network request
puts entry.content
Prints the content again without another network request
puts entry.content
“
Contributing
Bug reports and pull requests are welcome on GitHub.
License
The gem is available as open source under the terms of the MIT License.