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

Question

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;
  }
}

David Jencks · Accepted Answer · 2020-12-23T06:21:37.573

4

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.

edited Dec 23 '20 at 06:21

answered Dec 22 '20 at 23:35

David Jencks

96
2

Thanks, I have built a UI bundle and that does work. I was just hoping to always stay up to date with antora without having to rebuild the bundle. At least that was my goal. – jj2f1 Dec 23 '20 at 00:31
I totally sympathize with that; I think it is far harder than necessary to develop and maintain Antora UI bundles. I opened https://gitlab.com/antora/antora-ui-default/-/issues/110 and https://gitlab.com/antora/antora-ui-default/-/issues/111 to try to start some discussion on this problem and started prototyping my ideas in https://gitlab.com/djencks/antora-ui-builder. Without that I would have a lot less enthusiasm for building a UI bundle and a lot more for supplemental_files. You might consider voting for the issues or experimenting with the project. – David Jencks Dec 23 '20 at 06:58
I will have a look at the posted issues. And for anyone reading this later the issue I had was not adding a line to the partials/head-styles.hbs. Thank you! – jj2f1 Dec 23 '20 at 17:05

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

1 Answers1