mkdocs-extract-listings-plugin
Advanced tools
Create a page that contains all of your listings and/or a search function for listings
A small plugin to extract all your listings and put them in a single page. It can also generate a search function of code listings with different search methods (fuzzy match, substring, contains words).
You can try out the demo at https://mkdocs-extract-listings-plugin.six-two.dev.
It is configured to offer both the search and all listings pages an uses the plugin with some common MkDocs themes (mkdocs, readthedocs, and material).
The source for this demo is also in this repo (mkdocs.yml, docs/ and build.sh).
Install the plugin using pip:
pip install mkdocs-extract-listings-plugin
Add the plugin to your mkdocs.yml:
plugins:
- search
- extract_listings
If you have no
pluginsentry in your config file yet, you'll likely also want to add thesearchplugin. MkDocs enables it by default if there is nopluginsentry set.
More information about plugins in the MkDocs documentation.
Configure a page with all listings, a page with listing search, or both (see below).
Optional: To properly detect which language a listing belongs to, you may have to add the following to your mkdocs.yml as described in the Material for MkDocs page on code blocks:
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
Add a Markdown file for the page that will be filled with all the listings.
In that file add the placeholder where the listings should be inserted.
Then reference that file and specify the placeholder like this in your mkdocs.yml:
plugins:
- extract_listings:
listings_file: listings.md
placeholder: PLACEHOLDER_LISTINGS_PLUGIN
This is the simplest way and is recommended for most users:
search_page_path in your plugin settings to either a page path (it can already exist, but does not need to):
plugins:
- extract_listings:
search_page_path: plugin/index.md
search_page_create_if_missing:
plugins:
- extract_listings:
search_page_path: plugin/index.md
search_page_create_if_missing: True
It the page already exists, then a new section with the search box and results will be added. If it does not exist and should be created, then a page containing only the search box and results will be created.
This is more complicated to set up, but you have more control about the page:
Create a page, which should contain the search function.
Add a tag where the search elements should be inserted and load the search script:
<div id="listing-extract-search"></div>
<script src="/listing-search.js" async></script>
Specify where you want the plugin to write the script file to.
This should match the path you used in the previous step.
In mkdocs.yml:
plugins:
- extract_listings:
javascript_search_file: listing-search.js
I recommend using an absolute path for the script.src attribute, since it will keep working after moving the page or after switching between directory URLs and non directory URLs pages.
It just runs into problems when your base directory (where the page is deployed) is not the root directory or when you are using offline mode (from file:// URLs).
Alternatively you can include the script and the data inline, but this can have tiny performance drawbacks:
async or defer script attributes).You can configure the plugin like this:
plugins:
- extract_listings:
listings_file: listings.md
placeholder: PLACEHOLDER_LISTINGS_PLUGIN
javascript_search_file: listing-search.js
default_css: true
offline: false
default_search_mode: substr-i
exclude_language_list:
- python
- bash
search_page_path: ""
search_page_create_if_missing: false
search_page_section_name: Code Snippet Search
default_css determines, whether the search JavaScript should also load the default styling for the search dialog and results.
By default it is set to true, but you can set it to false if the theme you use does not work well with the style.
You should then define your own custom style and include it on the search page.
Also has some effect on the all listings page.
listings_file is expected to contain the relative path to the Markdown file, where the listings should be written to.
If the file does not exist, an error will be raised during the build process.
The default value is empty.
The value for placeholder will be searched in the file referenced by listings_file and be replaced with the list of all listings.
The JavaScript code for the search function will be written to this path. The default value is empty, meaning that neither the JSOn file nor the JavaScript are generated.
When set to true the listing data is included into the JavaScript file.
This way it can be used even when the site if opened from the file system (via a file:// URL).
The disadvantage is that the loading of the script will take longer and the data is not loaded asynchronously, so the loading of the page via the Internet will be delayed.
Because of that it is set to false by default.
Ignore any listings that are in the given languages. They will not appear on the all listings page or in the listings search.
The default search mode to use for all search pages.
This can be overwritten by the data-searchmode as shown below for individual search boxes.
Insert a search box and results on this page.
This allows you to use the plugin without needing to modify the Markdown files in your docs directory.
If the page specified by search_page_path does not exist, then create it and add it to the navigation.
The name of the section (if page exists) or the page title (if the page was newly created) that will be added to the page specified by search_page_path.
You can set the search mode via the data-searchmode attribute:
<div id="listing-extract-search" data-searchmode="substr"></div>
To see all current valid values inspect the search type dropdown menu using your browser's developer tools.
The data in the value attribute is the value you should put in the attribute:
Alternatively you can put in a random value and will receive an warning message in the developer tools, that also lists the valid values (but without descriptions).
search_page_path, search_page_create_if_missing and search_page_section_name settings, which allow adding a search page without touching any Markdown filesPLACEHOLDER_INLINE_LISTINGS_SEARCH_PLUGIN in a page to include the script and listings database inline into it.site_url property in mkdocs.yml).default_search_mode setting, which allows to set the default search mode.glob and glob-i search modes.exclude_language_list option which excludes listings in the given languages from the searchmermaid language when using MkDocs for Materialfile:// URLs:
offline: true setting.listings_file page.Contains words (case insensitive).use_directory_urls: false and not setting listings_file.default_css to disable it.//listings_file to empty string.Unknown path being shown on with different themes (readthedocs and material)FAQs
Create a page that contains all of your listings and/or a search function for listings
We found that mkdocs-extract-listings-plugin demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.
Research
Security News
Socket researchers uncovered a malicious PyPI package exploiting Deezer’s API to enable coordinated music piracy through API abuse and C2 server control.
Research
The Socket Research Team discovered a malicious npm package, '@ton-wallet/create', stealing cryptocurrency wallet keys from developers and users in the TON ecosystem.