Skip to content
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.

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

Support multiple MkDocs themes & styling from the same branch #108

Merged
merged 35 commits into from
Jan 22, 2024

Conversation

benkirk
Copy link
Collaborator

@benkirk benkirk commented Jan 21, 2024

This PR supports building different styles from the same branch by doing some tree reorg and using environment variables

Functionally this means we don’t need multiple branches to support the primary and iframe deployments.

Since our iframed site is a complete duplicate of content on the primary ReadTheDocs site,
don't allow search engine indexing or caching.
(ref: https://www.conductor.com/academy/meta-robots-tag/)
@benkirk benkirk marked this pull request as ready for review January 21, 2024 20:08
@benkirk
Copy link
Collaborator Author

benkirk commented Jan 22, 2024

The approach is as follows:

  1. Reorganize the source tree:

    mkdocs.yml
    theme.yml -> themes/NCAR_primary.yml
    themes/ 
    ├── NCAR_primary/
    │   ├── assets/
    │   │   └── [...]
    │   ├── css/
    │   │   └── NCAR_primary.css
    │   ├── main.html
    │   └── partials/
    │       └── footer.html
    ├── NCAR_primary.yml
    ├── arc_iframe/
    │   ├── assets/
    │   │   └── [...]
    │   ├── css/
    │   │   └── arc_iframe.css
    │   ├── main.html
    │   └── partials/
    │       ├── footer.html
    │       ├── header.html
    │       ├── logo.html
    │       ├── nav-item.html
    │       ├── nav.html
    │       └── source.html
    └── arc_iframe.yml
    

    mkdocs.yml uses the INHERIT: option to include theme.yml, which is in turn a symbolic link into the themes/ directory specifying which theme should be built.

  2. Use ReadTheDocs user-defined environment variables to distinguish the DEPLOY_TARGET at build time (primary site, iframe, etc...)

     # deploy the primary site: https://readthedocs.org/projects/ncar-hpc-docs/
     DEPLOY_TARGET=NCAR_primary
     
     # build the ARC iframed style site: https://readthedocs.org/projects/ncar-hpc-docs-arc-iframe/
     DEPLOY_TARGET=arc_iframe
    
  3. Use a ReadTheDocs pre_build rule to run a make command to update the appropriate symbolic links based on the DEPLOY_TARGET:

    # DEPLOY_TARGET is set in our readthedocs admin interface, and should
    # be one of the supported targets: [ NCAR_primary, arc_iframe ]
    make ${DEPLOY_TARGET}-stylelinks
    

    Note: This make step could be avoided with proper support for the !ENV mkdocs environment variable support, however at the time of this writing using this inside mkdocs.yml causes build failures (example) on the readthedocs build images. This feels like a bug and one I'd like to resolve, but likley will require a small stand-alone test case and support from ReadtheDocs.

  4. Right now the symbolic link theme.yml is committed to our repo, so a fresh clone will work with no environment variable nor make nonsense. This should not be changed, however, and we have a github action in place to be sure it points to the right location (theme.yml -> themes/NCAR_primary.yml). This complication could be overcome if/when we can use the !ENV yaml tag.

  5. Testing this required a separate ReadtheDocs instance, see for example https://ncar-hpc-docs-arc-iframe--108.org.readthedocs.build/en/108/


Finally, another change was implemented in this whole process. Since our iframed site is a complete duplicate of content on the primary ReadTheDocs site, we don't want search engine indexing or caching. This can be achieved with the following meta tag, which should NOT be present on NCAR_primary but included in any other restyled builds:

    <meta name="robots" content="noindex,nofollow,noarchive">

859011b

@benkirk benkirk merged commit 302ec0f into NCAR:main Jan 22, 2024
5 checks passed
@benkirk benkirk deleted the multiple_styles_rewrite branch January 22, 2024 23:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant