Setting Up and Managing a Conda Environment for MkDocs

1. Creating a New Conda Environment

environment.yml

Create an environment.yml file with the following content:

name: mkdocs-env
channels:
  - conda-forge
dependencies:
  - python=3.11
  - pip
  - jupyter
  - matplotlib
  - nbconvert
  - pip:
    - mkdocs
    - mkdocs-material
    - mkdocs-mermaid2-plugin
    - mkdocs-jupyter
    - mkdocs-bibtex
    - mkdocs-exclude

requirements.txt

Create a requirements.txt file with the following content:

mkdocs
mkdocs-material
mkdocs-mermaid2-plugin
mkdocs-jupyter
mkdocs-bibtex
mkdocs-exclude

Steps to Create the Environment

Create the Conda Environment:
```
conda env create -f environment.yml
```
Activate the Environment:
```
conda activate mkdocs-env
```
Install Additional pip Packages:
```
pip install -r requirements.txt
```

2. Updating an Existing Conda Environment

If you already have an environment named mkdocs-env and want to update it with new dependencies:

Steps to Update the Environment

Update the Conda Environment:

conda env update -f environment.yml --prune

Activate the Environment:
```
conda activate mkdocs-env
```
Install Additional pip Packages:
```
pip install -r requirements.txt
```

The --prune flag ensures that any dependencies that are no longer needed are removed.

3. Removing an Existing Conda Environment

If you need to remove an existing environment before creating a new one:

Steps to Remove and Recreate the Environment

Remove the Existing Environment:
```
conda env remove -n mkdocs-env
```
Create the Conda Environment:
```
conda env create -f environment.yml
```
Activate the Environment:
```
conda activate mkdocs-env
```
Install Additional pip Packages:
```
pip install -r requirements.txt
```

4. Including MathJax in MkDocs

Since mkdocs-mathjax is not available on PyPI, include MathJax via CDN in your mkdocs.yml configuration file:

Example `mkdocs.yml`

site_name: My MkDocs Site
theme:
  name: material

extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-mml-chtml.js

markdown_extensions:
  - extra
  - toc:
      permalink: true
  - pymdownx.superfences
  - pymdownx.inlinehilite
  - pymdownx.highlight
  - pymdownx.arithmatex

plugins:
  - search
  - mermaid2
  - mkdocs-jupyter
  - bibtex
  - exclude:
      glob:
        - "*.tmp"
        - "*.log"

Summary

Create or Update Conda Environment:
- conda env create -f environment.yml
- conda env update -f environment.yml --prune
Activate the Environment:
- conda activate mkdocs-env
Install pip Packages:
- pip install -r requirements.txt
Configure MathJax:
- Add MathJax via CDN in mkdocs.yml.

Following these steps will ensure your MkDocs environment is properly set up and maintained. If you have any further questions or run into issues, feel free to ask!

3.1 KiB Raw Blame History