Skip to content

Docs update #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jaywhj merged 2 commits into from
Apr 24, 2026
Merged

Docs update #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1a20f03
Fixed path issue for uploading docker hub
jaywhj Apr 24, 2026
eba2be5
Updated docs for docker
jaywhj Apr 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,8 +128,8 @@ jobs:
uses: docker/metadata-action@v5
with:
images: |
${{ github.repository.full_name }}
ghcr.io/${{ github.repository.full_name }}
docker.io/${{ github.repository }}
ghcr.io/${{ github.repository }}
tags: |
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
Expand Down
23 changes: 17 additions & 6 deletions CHANGELOG
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,15 @@

mkdocs-materialx-10.1.4 (2026-04-26)

- Added official Docker image, see [installation with docker](https://jaywhj.github.io/mkdocs-materialx/installation#with-docker)
- Updated documentation workflow
- Restored build workflow
- Optimized the date loading mechanism of the blog plugin
- Manual date configuration for each post is no longer required, and the date plugin no longer needs to be enabled
- Fixed inconsistent icon rendering sizes across different icon families when customizing Admonitions
- Fixed the issue where annotation tooltips inside admonitions were clipped
- Fixed issues arising from incorrect mounting logic for Code Annotations
- Significantly updated project documentation, including [plugins](https://jaywhj.github.io/mkdocs-materialx/plugins/index#graphics-charts), [setup](https://jaywhj.github.io/mkdocs-materialx/setup/adding-document-dates-authors), [admonitions](https://jaywhj.github.io/mkdocs-materialx/reference/admonitions#custom-icons-and-colors-example-2-create-new-admonitions) and more

mkdocs-materialx-10.1.3 (2026-04-10)

Expand All @@ -13,7 +24,7 @@ mkdocs-materialx-10.1.2 (2026-04-01)

- Fixed the robustness of the `document-dates` plugin when running with the blog plugin
- Fixed the border gap issue for `admonitions` & `details`
- Updated the usage documentation for the `document-dates` plugin, see [Configuration](https://jaywhj.github.io/mkdocs-materialx/setup/adding-document-dates-authors#configuration){target="_blank"}
- Updated the usage documentation for the `document-dates` plugin, see [Configuration](https://jaywhj.github.io/mkdocs-materialx/plugins/date-author#configuration){target="_blank"}
- Updated project development setup
- Archived unnecessary docs and exclude them from the build, see [Archives](https://github.com/jaywhj/mkdocs-materialx/tree/main/docs/archives){target="_blank"}

Expand All @@ -25,11 +36,11 @@ mkdocs-materialx-10.1.1 (2026-03-29)
- Added an override template for `sitemap.xml` that supports dynamically loading the exact lastmod to improve SEO, see [sitemap.xml
](https://github.com/jaywhj/mkdocs-materialx/blob/main/src/templates/sitemap.xml){target="_blank"}
- Updated the processing logic for blog post dates, manual date specification is no longer required
- These date values can be accessed via template variables in any template or plugin, see [Template Variables](https://jaywhj.github.io/mkdocs-materialx/setup/adding-document-dates-authors#template-variables){target="_blank"}
- These date values can be accessed via template variables in any template or plugin, see [Template Variables](https://jaywhj.github.io/mkdocs-materialx/plugins/date-author#template-variables){target="_blank"}
- Recently updated list
- Added high-performance readtime & summary parsers
- Added `readtime` and `tag` rendering, for readtime calculation details see [Reading-Time-Estimation](https://jaywhj.github.io/mkdocs-materialx/setup/adding-document-dates-authors#reading-time-estimation){target="_blank"}
- Added line count configuration for `summary`, see [Summary-Line-Configuration](https://jaywhj.github.io/mkdocs-materialx/setup/adding-document-dates-authors#summary-line-configuration){target="_blank"}
- Added `readtime` and `tag` rendering, for readtime calculation details see [Reading-Time-Estimation](https://jaywhj.github.io/mkdocs-materialx/plugins/date-author#reading-time-estimation){target="_blank"}
- Added line count configuration for `summary`, see [Summary-Line-Configuration](https://jaywhj.github.io/mkdocs-materialx/plugins/date-author#summary-line-configuration){target="_blank"}
- Improved layout styling for mixed text and image content
- Tags
- Fixed a bug in tag list parsing
Expand Down Expand Up @@ -95,8 +106,8 @@ mkdocs-materialx-10.0.4 (2026-01-02)

- New: Refactor the TOC components for mobile, now you can experience TOC perfectly on mobile!
- New: Show `git repo` in sidebar on mobile
- New: Add a new generation date author plugin, see doc [Add document dates authors](https://jaywhj.github.io/mkdocs-materialx/setup/adding-document-dates-authors/)
- New: Add recent updates module, see doc [Add recent updates module](https://jaywhj.github.io/mkdocs-materialx/setup/adding-recent-updates-module/)
- New: Add a new generation date author plugin, see doc [Add document dates authors](https://jaywhj.github.io/mkdocs-materialx/setup/adding-document-dates-authors)
- New: Add recent updates module, see doc [Add recent updates module](https://jaywhj.github.io/mkdocs-materialx/setup/adding-recent-updates-module)
- Fixed: Placing the back-to-top button at the bottom, this is more in line with the interaction logic of proximity operation
- Fixed: Optimize the judgment of the direction of the swipe gesture, so as to adjust the sensitivity of showing the bottom menu
- Fixed: Search function does not display properly on mobile
Expand Down
4 changes: 2 additions & 2 deletions docs/changelog/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ icon: material/layers-triple-outline

### 10.1.4 <small>April 26, 2026</small> { id="10.1.4" }

- Added official Docker image
- Added official Docker image, see [installation with docker](../installation.md#with-docker){target="_blank"}
- Updated documentation workflow
- Restored build workflow
- Optimized the date loading mechanism of the blog plugin
- Manual date configuration for each post is no longer required, and the date plugin no longer needs to be enabled
- Fixed inconsistent icon rendering sizes across different icon families when customizing Admonitions
- Fixed the issue where annotation tooltips inside admonitions were clipped
- Fixed issues arising from incorrect mounting logic for Code Annotations
- Significantly updated project documentation, including plugins, setup, admonitions and more
- Significantly updated project documentation, including [plugins](../plugins/index.md#graphics-charts), [setup](../setup/adding-document-dates-authors.md), [admonitions](../reference/admonitions.md#custom-icons-and-colors-example-2-create-new-admonitions) and more

### 10.1.3 <small>April 10, 2026</small> { id="10.1.3" }

Expand Down
44 changes: 12 additions & 32 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,74 +47,54 @@ This will automatically install compatible versions of all dependencies:

## with docker

The official [Docker image] is a great way to get up and running in a few
### official docker image

The official [Docker image]{target="_blank"} is a great way to get up and running in a few
minutes, as it comes with all dependencies pre-installed. Open up a terminal
and pull the image with:

=== "Latest"

```
docker pull squidfunk/mkdocs-material
docker pull jaywhj/mkdocs-materialx
```

=== "Pin"

```
docker pull squidfunk/mkdocs-material:9.7.1
docker pull jaywhj/mkdocs-materialx:10.1.4
```

The following plugins are bundled with the Docker image:

- [mkdocs-minify-plugin]
- [mkdocs-redirects]
- [mkdocs-minify-plugin]{target="_blank"}
- [mkdocs-redirects]{target="_blank"}

[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[Docker image]: https://hub.docker.com/r/jaywhj/mkdocs-materialx
[mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
[mkdocs-redirects]: https://github.com/datarobot/mkdocs-redirects

### Add more plugins
### add more plugins

Material for MkDocs only bundles selected plugins in order to keep the size of the official image small. If the plugin you want to use is not included, you can add them easily. Create a `Dockerfile` and extend the official image:

``` Dockerfile title="Dockerfile"
FROM squidfunk/mkdocs-material:9.7.1
RUN pip install mkdocs-materialx
FROM jaywhj/mkdocs-materialx
RUN pip install mkdocs-glightbox
```

### For MaterialX

MaterialX does not yet provide an official Docker image, as a temporary solution, you can derive a custom image from `mkdocs-material`.

> This approach reuses the official `mkdocs-material` image and installs MaterialX on top of it.

#### Create a Dockerfile

```dockerfile title="Dockerfile" hl_lines="3"
FROM squidfunk/mkdocs-material:9.7.1

RUN pip install mkdocs-materialx

# Install additional plugins if needed
# RUN pip install mkdocs-glightbox ...
```

#### Build the image
#### build the image

```
docker build -t materialx .
```

#### Run the container
#### run the container

```
docker run -p 8000:8000 -v ${PWD}:/docs materialx
```

!!! info

This is a temporary workaround, an official MaterialX Docker image will be provided in the future.

## with git

You can also clone the source code from a GitHub repo via `git clone` and install it locally:
Expand Down
Loading