MkDocs plugin: 3d viewer

Render 3D files in your documentation

Links

Examples:

• Usage examples

Code:

• Online documentation
• Code
• Issues
• Migration guide
• Change log

Community:

• Code of conduct

Usage

There is no pypi module for now; use the git repository. If you need a specific reference, append it to the repository url with @<ref>.

Pip:

pip install git+https://gitlab.com/experimentslabs/mkdocs_3d_viewer.git

Or, with requirements.txt:

package_name @ git+https://gitlab.com/experimentslabs/mkdocs_3d_viewer.git

Or, in a pyproject.yml:

dependencies= [
  #...
  "package_name @ git+https://gitlab.com/experimentslabs/mkdocs_3d_viewer.git",
]

Then, add the plugin to mkdocs.yml:

#...

# If there is no "plugin" section, and you use the search plugin, you need to explicitly add it to the
# list as the "plugin" section replace the default "plugins" instead of completing it
plugins:
  - search
  - mkdocs_3d_viewer

Then, in Markdown documents:

[3d: /path/to/file.stl]

Or with a relative path:

[3d: path/to/file.stl]

Or with a URL:

[3d: https://example.com/path/to/file.stl]

A few attributes are supported to control the widget:

• {% 3d: file.stl render-now=true }: whether to force rendering the model. Defaults to file size check.
• {% 3d: file.stl controls=false }: whether to display the control buttons. Defaults to true

Configuration

You can override default values with these plugin options:

# mkdocs.yml
plugins:
  search: {}
  mkdocs_3d_viewer:
    # When files are larger than this value, they won't be loaded automatically.
    # Use 0 to prevent all files to be auto-loaded, and an extra large value if
    # you want them to always be auto-loaded.
    #
    # Defaults to 51200 (50kb)
    max_file_size: 51200

Contributing

Bug reports and pull requests are welcome on the issue tracker at GitLab. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Setup

First of all, clone the repository.

The following steps creates a Python virtual environment to develop this project.

Create a Python environment:

pyenv install 3.13
pyenv virtualenv 3.13 mkdocs_3d_viewer

Activate the env:

pyenv local mkdocs_3d_viewer

Install dependencies:

pip install --editable '.[dev]'

Start the documentation server to see the changes:

poe dev

Linting and formatting

To check all the code:

poe lint-check

To fix what is fixable automatically:

poe lint-fix

Checking licenses

To help ensuring the project has a valid license, run licensecheck; it will compare the license with the ones of the dependencies.

You only have to run it when dependencies changes.

Testing

Run unit tests with:

poe test

Documentation

Documentation is generated in CI. To generate it locally:

# Copies markdown files and generate pictures; there is no need to run it every time.
scripts/prepare_documentation.sh

# Serve documentation locally
poe dev
# Open your browser at the link given by the server.

License

This library is available as open source under the terms of the GPL v3 License.

Code of Conduct

Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.