Package: mkdocs-extract-listings-plugin
mkdocs-extract-listings-pluginA 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).DemoYou can try out the demo athttps://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/andbuild.sh).SetupInstall the plugin using pip:pipinstallmkdocs-extract-listings-pluginAdd the plugin to yourmkdocs.yml:plugins:-search-extract_listingsIf you have nopluginsentry 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 theMkDocs documentation.Configure a page with all listings, a page with listing search, or both (see below).Listing pageAdd 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 yourmkdocs.yml:plugins:-extract_listings:listings_file:listings.mdplaceholder:PLACEHOLDER_LISTINGS_PLUGINListing searchCreate 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.
Inmkdocs.yml:plugins:-extract_listings:javascript_search_file:listing-search.jsConfigurationYou can configure the plugin like this:plugins:-extract_listings:listings_file:listings.mdplaceholder:PLACEHOLDER_LISTINGS_PLUGINjavascript_search_file:listing-search.jsdefault_css:trueoffline:falsedefault_cssdefault_cssdetermines, whether the search JavaScript should also load the default styling for the search dialog and results.
By default it is set totrue, but you can set it tofalseif 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_filelistings_fileis 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.placeholderThe value forplaceholderwill be searched in the file referenced bylistings_fileand be replaced with the list of all listings.javascript_search_fileThe 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.offlineWhen set totruethe 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 afile://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 tofalseby default.Search modeYou can set the search mode via thedata-serachmodeattribute:<divid="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 thevalueattribute 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).ChangelogVersion 0.1.1Fix: Links incorrect if search page is not in the root directory.Version 0.1.0The plugin should now be able to work when served fromfile://URLs:Search JSON can be inlined to the script viaoffline: truesetting.Use relative links on thelistings_filepage.Improved the search code:Allow users to specify which matching mode the search uses by default.Added modeContains words (case insensitive).Fixed crash when usinguse_directory_urls: falseand not settinglistings_file.Version 0.0.4Added styling for the search page and the optiondefault_cssto disable it.Fixed bug: URL for index pages starts with//Version 0.0.3Added snippet search JavaScript and JSON file.Changed default forlistings_fileto empty string.Version 0.0.2FixedUnknown pathbeing shown on with different themes (readthedocsandmaterial)