Andrius Velykis created MSITE-702:
-------------------------------------
Summary: Overriding skin resources / Duplicate copying of skin
resources
Key: MSITE-702
URL: https://jira.codehaus.org/browse/MSITE-702
Project: Maven Site Plugin
Issue Type: Bug
Affects Versions: 3.3
Reporter: Andrius Velykis
Attachments: site-resources-test.zip
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()}}|http://maven.apache.org/plugins/maven-site-plugin/xref/org/apache/maven/plugins/site/SiteMojo.html#151],
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()}}|http://maven.apache.org/doxia/doxia-sitetools/doxia-site-renderer/xref/org/apache/maven/doxia/siterenderer/DefaultSiteRenderer.html#728].
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}}|http://maven.apache.org/plugins/maven-site-plugin/xref/org/apache/maven/plugins/site/SiteMojo.html#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|http://andriusvelykis.github.io/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|http://getbootstrap.com/customize/] 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.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
