[MSITE-702] Overriding skin resources / Duplicate copying of skin resources

• Type: Bug
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 3.3
• Fix Version/s: 3.5
• Assignee: Herve Boutemy
• Reporter: Andrius Velykis
• Created: 06/Jan/14 07:30
• Updated: 20/Dec/15 20:09
• Resolved: 20/Dec/15 20:09

Description

I am trying to override some resources in a Maven site skin by placing files with the same name into my /src/site/resources/ directory. For example, if I were to use the default skin and want to override some file (say css/maven-theme.css), I would create a file /src/site/resources/css/maven-theme.css in my Maven project and generate site with mvn site. However, in the generated site, the maven-theme.css file from the skin JAR is used rather than my overriding copy.

I was wondering whether this is actually allowed by design in Maven site. I investigated the code and saw some interesting cases there regarding this issue.

In SiteMojo#renderLocale(), the site is rendered twice: first with normal resource directories and then with generated-site. During each rendering (siteRenderer.render()), all skin resources are copied to the target directory: see DefaultSiteRenderer#copyResources(). After copying the skin resources, the extra site resources from the src/site/resources directory are copied, overwriting the skin resources.

So in general, the code seems to allow overriding the skin resources with the ones in src/site/resources. However, the double-rendering of the site results in the following steps regarding the overridden file:

1. maven-theme.css is copied to /target from the skin JAR (normal rendering)
2. maven-theme.css is overridden from the src/site/resources (normal rendering) <- I want this!
3. maven-theme.css is AGAIN copied to /target from the skin JAR (generated-site rendering)
4. resources from target/generated-site/resources are copied to /target/site, however maven-theme.css is not there. (generated-site rendering)

Therefore the 3rd step reverts my override. I could still achieve what I want by having a build step that copies everything from src/site/resources to target/generated-site/resources, which would ensure that my file is the last one copied, but it would be an unnecessary workaround..

I am thinking that skin files only need to be copied once during the generation process. This would allow overriding files nicely. The second rendering (SiteMojo:191) of the generated-site sources should not repeat the original process.

Would this be doable? By overriding resource files, it would be possible, for example, to adjust images in the skin without creating and maintaining a new skin. In my case (Reflow Maven skin), I want to allow overriding the Twitter Bootstrap files. I would package the default bootstrap.min.css with the skin, but the users would be able to override the file with their own configuration. The Bootstrap customization or various available themes produce a full bootstrap.min.css file, where it is easier to replace the package skin's version rather than using site.css. site.css could have site-specific customisations, while the theme would be placed in bootstrap.min.css.

I have attached a small Maven site project. I have added src/site/resources/css/maven-theme.css to the resources but in the generated site, the skin's maven-theme.css is still used.

Issue Links

• depends upon: DOXIASITETOOLS-132 do not override existing content with template when copyResources()