diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea930474a..ce1537231 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,7 @@ The following is a set of guidelines for contributing to the project. These are 1. [Tell us your story](#tell-us-your-story) 1. [Write code for a component](#write-code-for-a-component) 1. [Write documentation](#write-documentation) + 1. [Building the Documentation Locally](#building-the-documentation-locally) ## Code of Conduct @@ -98,6 +99,25 @@ There is a rich component styling framework that is part of this library for you The documentation for the migration and consumption of these components will be significant in scope and need to cover many scenarios. We are always looking for help to add content to the `/docs` section of the repository with proper links back through to the main `/README.md`. -### Recources +#### Building the Documentation Locally + +The documentation is built using [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/). To build and preview the documentation locally: + +```bash +# Build the mkdocs Docker image +docker build -t mkdocs -f ./docs/Dockerfile ./ + +# Build docs (from repository root) +docker run --rm -v "$(pwd):/docs" mkdocs build --strict + +# Serve docs locally for preview +docker run --rm -p 8000:8000 -v "$(pwd):/docs" mkdocs serve --dev-addr 0.0.0.0:8000 +``` + +The documentation will be available at http://localhost:8000 + +The docs are automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch via the `.github/workflows/docs.yml` workflow. + +### Resources [cmjchrisjones Blog: Contributing To Someone else's git repository](https://cmjchrisjones.dev/posts/contributing-to-someone-elses-git-repository/) diff --git a/docs/Dockerfile b/docs/Dockerfile index 6a13d54a7..0a9dcc161 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -1,14 +1,14 @@ -FROM squidfunk/mkdocs-material:5.5.0 +FROM squidfunk/mkdocs-material:9.7.1 -RUN apk add --no-cache \ - git \ - git-fast-import \ - openssh \ - && apk add --no-cache --virtual .build gcc musl-dev \ +RUN \ + apk add --no-cache \ + git \ + git-fast-import \ + openssh \ && pip install --no-cache-dir \ - 'markdown-include==0.5.1' \ - 'mike==1.1.2' \ - 'mkdocs-exclude==1.0.2' \ - 'mkdocs-macros-plugin==0.5.12' \ - && apk del .build gcc musl-dev \ + 'markdown-include' \ + 'mike' \ + 'mkdocs-exclude' \ + 'mkdocs-macros-plugin' \ + 'mkdocs-git-revision-date-localized-plugin' \ && rm -rf /tmp/* diff --git a/mkdocs.yml b/mkdocs.yml index 3e35c7077..b34b898fe 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,25 +25,26 @@ theme: code: Roboto Mono logo: assets/logo.png favicon: assets/favicon.ico - include_search_page: false - search_index_only: true extra_css: - assets/stylesheets/extra.css markdown_extensions: - admonition - - codehilite + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite - footnotes - markdown_include.include: base_path: docs - meta - pymdownx.details - - pymdownx.tabbed + - pymdownx.tabbed: + alternate_style: true - pymdownx.superfences - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - toc: permalink: true @@ -56,7 +57,6 @@ plugins: type: iso_datetime - macros - search: - prebuild_index: python lang: - en diff --git a/samples/AfterBlazorServerSide/Dockerfile b/samples/AfterBlazorServerSide/Dockerfile index a175f54a1..5db419e62 100644 --- a/samples/AfterBlazorServerSide/Dockerfile +++ b/samples/AfterBlazorServerSide/Dockerfile @@ -7,6 +7,7 @@ EXPOSE 443 FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build WORKDIR /src +COPY ["Directory.Build.props", "./"] COPY ["samples/AfterBlazorServerSide/AfterBlazorServerSide.csproj", "samples/AfterBlazorServerSide/"] COPY ["src/BlazorWebFormsComponents/BlazorWebFormsComponents.csproj", "src/BlazorWebFormsComponents/"] COPY ["samples/SharedSampleObjects/SharedSampleObjects.csproj", "samples/SharedSampleObjects/"]