Create a page that contains all of your listings and/or a search function for listings
Project description
mkdocs-extract-listings-plugin
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).
Demo
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
).
Setup
-
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
plugins
entry in your config file yet, you'll likely also want to add thesearch
plugin. MkDocs enables it by default if there is noplugins
entry set.More information about plugins in the MkDocs documentation.
-
Configure a page with all listings, a page with listing search, or both (see below).
Listing page
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
Listing search
-
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">
-
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
Configuration
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
default_css
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
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.
placeholder
The value for placeholder
will be searched in the file referenced by listings_file
and be replaced with the list of all listings.
javascript_search_file
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.
Changelog
Version 0.0.4
- Added styling for the search page and the option
default_css
to disable it. - Fixed bug: URL for index pages starts with
//
Version 0.0.3
- Added snippet search JavaScript and JSON file.
- Changed default for
listings_file
to empty string.
Version 0.0.2
- Fixed
Unknown path
being shown on with different themes (readthedocs
andmaterial
)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-extract-listings-plugin-0.0.4.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3e969bf5417c5120195341a3f27623d785a8f7348a798b40bd501bba57afda95 |
|
MD5 | dfec1290b968781e4eb9cff3d8660619 |
|
BLAKE2b-256 | 2a469aa82152c979ce220e53511e88d55c828f8adc740ef083a859a719a90bf1 |
Hashes for mkdocs_extract_listings_plugin-0.0.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a2ee7447ae638f8b84d6931d87738312b4305dddda428f8d8fc41b12feb61c0c |
|
MD5 | 230c5c2e140e275fb98c7e07702bf8d2 |
|
BLAKE2b-256 | a2c042f04042f7ac5943d11c57b642acd5f1a63adf900a8aada1bed64e43310e |