MkDocs Homepage Copier

Reuse the README.md file by copying it into the docs/ directory as the docs/index.md file

Linting

Isort, black, and flake8 are used to check that code is well formatted and styled. Pre-commit hooks are used to automate this process.

• Install pre-commit package: pip install pre-commit
• Install git hook scripts: pre-commit install
• (optional) Run against all files: pre-commit run --all-files

Testing

To run tests:

• Install pytest and coverage: pip install pytest coverage
• Run tests: coverage run --source="copier" -m pytest
• (optional) View coverage report: coverage report

Usage

Install the package via pip:

• pip install mkdocs-homepage-copier

Or install the package from source:

• git clone https://github.com/onyonkaclifford/MkDocs-homepage-copier.git
• cd MkDocs-homepage-copier
• pip wheel --no-deps . -w dist
• pip install dist/mkdocs_homepage_copier-{version}-py3-none-any.whl

Enable the plugin in mkdocs.yml:

plugins:
  - search
  - mkdocs-homepage-copier
nav:
  - Home: index.md

If the file to be copied is not named README.md and/or the destination path isn't docs/index.md, use the parameters src and dest to identify the correct file to be copied and the correct destination path it's to be copied to. Either one, both, or none of the two parameters can be used depending on the need.

plugins:
  - search
  - mkdocs-homepage-copier:
      src: source.md
      dest: path/to/destination.md
nav:
  - Navigation option: path/to/destination.md

To disable mkdocs-homepage-copier, set the copy parameter to false. To re-enable, set it to true or remove it from mkdocs.yml, as it's set to true by default.

plugins:
  - search
  - mkdocs-homepage-copier:
      copy: false

To copy extra files in addition to the homepage file, use the extras parameter.

plugins:
  - search
  - mkdocs-homepage-copier:
      src: source.md
      copy: false
      extras:
        - src: path/to/source1.md
          dest: path/to/destination1.md
          copy: true
        - src: path/to/source2.md
          dest: path/to/destination2.md
          copy: false