Skip to content

Commit d8bdf7b

Browse files
rmseifriedrmseifried
authored
Merge pull request #294 from geoblacklight/mike-versions
Use mike for publishing versioned docs
2 parents 98c9e81 + ad622b8 commit d8bdf7b

6 files changed

Lines changed: 81 additions & 60 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,4 @@ jobs:
1515
python-version: 3.x
1616
cache: pip
1717
- run: pip install -r requirements.txt
18-
- run: mkdocs gh-deploy --force
18+
- run: mike deploy --push latest

docs/CNAME renamed to CNAME

File renamed without changes.

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ If you want to preview changes before committing them, follow the steps below. I
5656
1. Start a local server with the following command:
5757

5858
```
59-
mkdocs serve
59+
mike serve
6060
```
6161

6262
This will allow you to preview the site as you edit it. You will see text in the Terminal that looks something like this:

‎README.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,31 @@ This is the working branch containing the content for the site using Markdown.
5252

5353
This is the published branch containing the HTML code for the site. (We do **not** edit this branch directly).
5454

55-
* `index.html`: an HTML file containing the information in the `index.md` file in your Main branch
55+
Note that as of [this pull request](https://github.com/geoblacklight/geoblacklight.github.io/pull/294) the docs are separated by GeoBlacklight version. The `mike` library is used to manage the deployment of docs for each version, instead of `mkdocs`. The [`mkdocs` documentation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/) is useful for understanding how to integrate with `mike`, as well as [this blog post](https://blog.lx862.com/blog/2025-06-10-versioning-with-material-mkdocs/).
56+
57+
Each version is kept in a separate directory named after the version number, e.g. `4.x`, `5.x`, etc. Versions also have "aliases", which are names that point to specific versions. These are implemented as symlinks that point to a particular version directory. Currently, we only use the `latest` alias.
58+
59+
To publish a new version of whatever the `latest` alias currently points to, on the `main` branch, you would run:
60+
61+
```sh
62+
mike deploy --push latest
63+
```
64+
65+
If a new version is being created and it should become the new `latest`, on the `main` branch, you would instead run:
66+
67+
```sh
68+
mike deploy --push <new_version> --update-aliases latest
69+
```
70+
71+
To update the docs for a previous version, you need to be on the branch corresponding to that version (e.g. `4.x` branch for version `4.x`), and then run:
72+
73+
```sh
74+
mike deploy --push <version>
75+
```
76+
77+
Each version directory contains an entirely separate copy of the following:
78+
79+
* `index.html`: an HTML file containing the information in the `index.md` file at the time the version was published
5680
* The rest of your markdown content pages with be in separate directories. The directory name is the name of the markdown file and it contains an HTML file called `index.html`
5781
* `/images` and `/stylesheets` : same as the Main branch
5882
* `/assets` : contains **subdirectories** for `/images`, `/javascripts`, and `/stylesheets`. These subdirectories contain the favicon and compiled code.

‎mkdocs.yml‎

Lines changed: 53 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@ copyright: GeoBlacklight Community &copy; 2015 - 2025
66
theme:
77
name: material
88
logo: images/gbl-favicon.png
9-
favicon: images/gbl-favicon.png
9+
favicon: images/gbl-favicon.png
1010
palette:
1111
primary: white
12-
12+
1313
features:
1414
- content.code.copy
1515
- content.code.annotate
@@ -23,10 +23,9 @@ theme:
2323
- tags: {}
2424
index_page: tags.md
2525

26-
2726
extra_css:
2827
- stylesheets/extra.css
29-
28+
3029
markdown_extensions:
3130
- attr_list
3231
- md_in_html
@@ -54,19 +53,19 @@ markdown_extensions:
5453
options:
5554
custom_icons:
5655
- overrides/.icons
57-
56+
5857
extra_javascript:
59-
- https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
60-
- javascripts/tablesort.js
61-
58+
- https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
59+
- javascripts/tablesort.js
60+
6261
plugins:
6362
- search
6463
- table-reader
6564
- git-revision-date-localized
6665
- blog:
6766
blog_dir: blog
68-
# blog_toc: true
69-
# categories_toc: true
67+
# blog_toc: true
68+
# categories_toc: true
7069
post_date_format: medium
7170
post_url_date_format: yyyy/MM
7271
post_excerpt: optional
@@ -76,61 +75,58 @@ plugins:
7675
kwds:
7776
case: lower
7877

79-
8078
extra:
81-
social:
82-
- icon: fontawesome/brands/github
83-
link: https://github.com/GeoBlacklight
84-
- icon: fontawesome/brands/slack
85-
link: https://geo4lib.slack.com
86-
- icon: fontawesome/solid/paper-plane
87-
link: https://groups.google.com/g/geo4lib-community
79+
version:
80+
provider: mike
81+
alias: true
82+
social:
83+
- icon: fontawesome/brands/github
84+
link: https://github.com/GeoBlacklight
85+
- icon: fontawesome/brands/slack
86+
link: https://geo4lib.slack.com
87+
- icon: fontawesome/solid/paper-plane
88+
link: https://groups.google.com/g/geo4lib-community
8889

8990
nav:
90-
- Home: 'index.md'
91-
- About: 'about.md'
92-
- Community: 'community.md'
93-
- Showcase:
91+
- Home: "index.md"
92+
- About: "about.md"
93+
- Community: "community.md"
94+
- Showcase:
9495
- showcase/index.md
95-
- Blog:
96+
- Blog:
9697
- blog/index.md
97-
- Documentation:
98-
- 'docs/index.md'
98+
- Documentation:
99+
- "docs/index.md"
99100
- Install:
100-
- 'Quick Start': 'docs/geoblacklight_quick_start.md'
101-
- 'For Developers': 'docs/developers.md'
102-
- 'Tutorials': 'docs/tutorials.md'
101+
- "Quick Start": "docs/geoblacklight_quick_start.md"
102+
- "For Developers": "docs/developers.md"
103+
- "Tutorials": "docs/tutorials.md"
103104
- Running in Production:
104-
- 'Hardware Recommendations': 'docs/hardware_recommendations.md'
105-
- 'Implementation Recommendations': 'docs/implementation_recommendations.md'
106-
- 'Framework Recommendations': 'docs/framework-recommendations.md'
107-
- 'User Authentication': 'docs/user_authentication.md'
108-
- 'Using an External Solr Instance': 'docs/external_solr.md'
109-
- 'Periodic Maintenance': 'docs/periodic_maintenance.md'
105+
- "Hardware Recommendations": "docs/hardware_recommendations.md"
106+
- "Implementation Recommendations": "docs/implementation_recommendations.md"
107+
- "Framework Recommendations": "docs/framework-recommendations.md"
108+
- "User Authentication": "docs/user_authentication.md"
109+
- "Using an External Solr Instance": "docs/external_solr.md"
110+
- "Periodic Maintenance": "docs/periodic_maintenance.md"
110111
- Customization:
111-
- 'Configure the Settings': 'docs/settings.md'
112-
- 'Update the Catalog Controller': 'docs/catalog_controller.md'
113-
- 'Configure Search Relevancy': 'docs/solr_search_relevancy.md'
114-
- 'Customize Leaflet': 'docs/leaflet.md'
115-
- 'Add Mirador IIIF Viewer': 'docs/adding_mirador_viewer.md'
116-
- 'Add Thumbnail Images': 'docs/item_images.md'
117-
- 'Add SVG Icons': 'docs/adding_svg_icons.md'
118-
- 'Add Data Relations Widget': 'docs/data_relations_widget.md'
119-
- 'Render HTML in Metadata Fields': 'docs/rendering_html_from_description.md'
112+
- "Configure the Settings": "docs/settings.md"
113+
- "Update the Catalog Controller": "docs/catalog_controller.md"
114+
- "Configure Search Relevancy": "docs/solr_search_relevancy.md"
115+
- "Customize Leaflet": "docs/leaflet.md"
116+
- "Add Mirador IIIF Viewer": "docs/adding_mirador_viewer.md"
117+
- "Add Thumbnail Images": "docs/item_images.md"
118+
- "Add SVG Icons": "docs/adding_svg_icons.md"
119+
- "Add Data Relations Widget": "docs/data_relations_widget.md"
120+
- "Render HTML in Metadata Fields": "docs/rendering_html_from_description.md"
120121

121122
- Upgrade:
122-
- 'Upgrade to Version 4.0': 'docs/upgrade_version_4_0.md'
123-
- 'Upgrade to Version 2.0': 'docs/upgrade_version_2_0.md'
123+
- "Upgrade to Version 4.0": "docs/upgrade_version_4_0.md"
124+
- "Upgrade to Version 2.0": "docs/upgrade_version_2_0.md"
124125
- Reference:
125-
- 'Glossary': 'docs/glossary.md'
126-
- 'Settings.yml fields': 'docs/settings-yml.md'
127-
- 'Metadata Fields': 'docs/metadata.md'
128-
- 'Software Releases': 'docs/releases.md'
129-
- 'Index Maps': 'docs/index_maps.md'
130-
- 'GeoPackages': 'docs/geopackages.md'
131-
- 'JSONs and GeoJSONs': 'docs/json-geojson.md'
132-
133-
134-
135-
136-
126+
- "Glossary": "docs/glossary.md"
127+
- "Settings.yml fields": "docs/settings-yml.md"
128+
- "Metadata Fields": "docs/metadata.md"
129+
- "Software Releases": "docs/releases.md"
130+
- "Index Maps": "docs/index_maps.md"
131+
- "GeoPackages": "docs/geopackages.md"
132+
- "JSONs and GeoJSONs": "docs/json-geojson.md"

‎requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ mkdocs-material-extensions
44
mkdocs-table-reader-plugin
55
mkdocs-git-revision-date-localized-plugin
66
pymdown-extensions
7+
mike

0 commit comments

Comments
 (0)