cssantora

Antora supplemental-ui removing max-width from doc in doc.css


I am using antora for documenting a product architecture specification. We have large diagrams so allowing the svg images to scale up as large as possible when maximizing the browser window is a big plus.

I am not even a css novice. I know almost nothing. I can build antora documents (web pages) so I know only a tiny bit of antora from a user perspective.

I found this comment on how to make the scaling work. https://gitter.im/antora/users?at=5d97c8ea37073b36a06fddb8

I can get the desired results if I edit doc.css, build a ui-bundle.zip, point local-antora-playbook.yml at the newly created ui-bundle.zip and rebuild the site.

.doc {
  color: var(--doc-font-color);
  font-size: var(--doc-font-size);
  hyphens: auto;
  line-height: var(--doc-line-height);
  margin: var(--doc-margin);
  /* max-width: var(--doc-max-width); */
  padding: 0 1rem 4rem;
}

@media screen and (min-width: 1024px) {
  .doc {
    flex: auto;
    font-size: var(--doc-font-size--desktop);
    margin: var(--doc-margin--desktop);
    /* max-width: var(--doc-max-width--desktop); */
    min-width: 0;
  }
}

This is the suggested edit in the comment link I found and posted just above. I would prefer to use the supplemental-ui approach that is referenced here; Antora top navigation bar customization and actually used by the documentation for antora https://gitlab.com/antora/docs.antora.org.

I can see that my edited doc.css gets created in the new site when I build via a supplemental-ui approach. However, I don't get the desired results of being able to use the max-width of the web browser when maximized. I understand that in css if you declare something later it takes precedence. I'm wondering if the absence of a max-width is simply not being observed because of the order of sourcing files. I've tried different file names like doc.css and xdoc.css thinking they were sourced alphabetically. This didn't seem to help.

Is there a way to make this small css change and use the supplemental-ui approach of getting it into my antora site when I build it?

I would like the supplemental-ui approach to work so we can always stay up to date with antora changes and only have our tiny change to max-width. The approach I have working requires building antora with the tiny change and pointing at that new zip file to build antora instead of sourcing the current latest antora in the public antora repo.

For debug I also tried this approach with the supplemental-ui build procedure. I understand !important is not recommended but I was just trying to figure out if I could get something working other than the full build to a zip file.

.doc {
  color: var(--doc-font-color);
  font-size: var(--doc-font-size);
  hyphens: auto;
  line-height: var(--doc-line-height);
  margin: var(--doc-margin);
  /* max-width: var(--doc-max-width); */
  max-width: none !important;
  padding: 0 1rem 4rem;
}

@media screen and (min-width: 1024px) {
  .doc {
    flex: auto;
    font-size: var(--doc-font-size--desktop);
    margin: var(--doc-margin--desktop);
    /* max-width: var(--doc-max-width--desktop); */
    max-width: none !important;
    min-width: 0;
  }
}

Solution

  • It's possible to alter the effective css using supplemental UI but is slightly less performant (requiring fetching an additional css file) and I don't recommend it. The process of building a UI bundle puts all the css into one optimized file, which cannot really be modified later using supplemental UI. Therefore what you have to do is add a "new" css file in your supplemental UI containing the modifications or overrides you want, and also include a partial that pulls in your additional file.

    For instance, if your additional file is css/expand-svg.css, you'd need also a partials/head-styles.hbs containing

        <link rel="stylesheet" href="{{uiRootPath}}/css/site.css">
        <link rel="stylesheet" href="{{uiRootPath}}/css/expand-svg.css">
    

    I tried this with the additional css file containing

    .doc {
        max-width: none;
    }
    
    @media screen and (min-width: 1024px) {
        .doc {
            max-width: none;
        }
    }
    

    and it appears to work as you want. The !important isn't needed as the additional css appears later than the default UI css so overrides it.