0

In a Maven project with subprojects, each subproject gets an index.html with some content that comes from its POM's description element.

In one of these subprojects, I need that content to contain additional information, including links. There is a section of the doc that suggests I should not do it by trying to put HTML markup in CDATA in the description element (in fact, that doesn't work anyway; the HTML markup just comes out literal). Instead, it suggests there is some better way to get my own content included in the file.

While this element can be specified as CDATA to enable the use of HTML tags within the description, it is discouraged to allow plain text representation. If you need to modify the index page of the generated web site, you are able to specify your own instead of adjusting this text.

Can anyone describe how to do that? I have tried several methods unsuccessfully (I can supply Markdown files with other names and they generate HTML, but a subproject's index.md has no effect on the generated index.html). I have also read about the custom element in site.xml but it seems to require writing a custom Velocity template for the site; I hope the passage "you are able to specify your own" must mean there is some method more straightforward than that.

Of course I would also appreciate a pointer into the docs if there is already an answer I have simply failed to find. (Just pointing me to docs I've already read isn't in itself helpful, though pointing out the answer I missed would be helpful, if it's there.)

In response to inquiries

Directory structure under src/site:

src/site
src/site/resources
src/site/resources/images
src/site/markdown
src/site/markdown/use
src/site/markdown/install
src/site/markdown/examples
src/site/markdown/build

maven-site-plugin version: 3.4

What I mean by 'adding a link':

The part of the index.html that comes from the POM description element is the central content of the page (not the navigation bar, not the sidebar menus, but the actual content).

I would like that actual-content portion of the page to be able to have a paragraph or two explaining that this is a generated page for developers, and providing links (HTML <a href=...>) for people who arrived at the page from a web search but are really looking for the user-oriented pages.

I can't put that in the description element (even using CDATA), because HTML elements just come out literal. A comment below gives a link to a page on writing a whole custom Velocity template for the site, but is there honestly no simpler way to accomplish this?

Chapman Flack
  • 604
  • 5
  • 13
  • Could you post the structure of your project under `src/site`? What version of `maven-site-plugin` are you using? Also, could you post an example of wanted output versus actual output? Because it's not clear what you mean by "adding a link". – Tunaki Feb 21 '16 at 23:09
  • 1
    Wait - what part is rant? I'll take it back out. I don't think there's anything wrong with the Maven machine-generated page _per se_, but you can understand that it isn't what _every audience_ is looking for, and all I want to do is put some links on it so if they end up there, they can find the pages they do want. Am I ranting if I say that? – Chapman Flack Feb 21 '16 at 23:27
  • "Meanwhile, there are actual useful human-written documentation pages about the examples". Read that again. Just so you know, the docs are there: https://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html and there https://maven.apache.org/plugins/maven-site-plugin/examples/templatefile.html Cya – Tunaki Feb 21 '16 at 23:29
  • Making every effort to address your concern, I have reworded again to make it completely clear that I meant the pages that were written specifically to be useful to an expected audience, and that I am not knocking the generated file at all (which is just fine, _for a different audience_) and all I want is to expand the description/content on that page so when the wrong audience ends up there, they have a way to get where they are going. And now you (whether it was your final act or not) have given me two links, both of which I read before posting (one of which _I included in the post_). – Chapman Flack Feb 21 '16 at 23:46
  • See answer: cannot be reproduced. – Tunaki Feb 22 '16 at 08:23

2 Answers2

1

I have the same issue. The only thing the generated index.html gives you of value is the list of modules. You can add your own index.md page to src/site/markdown, putting in whatever content you want. To reproduce the list of modules, include something like this:

###Project Modules

This project has declared the following modules:

| Name | Description |

|-|-|

|[Module1 name](module1/index.html)| Module 1 description|  


|-|-|

|[Module2 name](module2/index.html)| Module 2 description|

Of course the text is not lifted from the POM. You also have to manually change this file if you have a new module. Not a perfect solution, but the best I could come up with.

sschale
  • 5,168
  • 3
  • 29
  • 36
Douglass Parker
  • 181
  • 1
  • 3
0

Where I wrote:

I can supply Markdown files with other names and they generate HTML, but a subproject's index.md has no effect on the generated index.html

it turns out the truth is more complex. In a project with subprojects, there are two places such an index.md might go: in src/site/markdown/subproject-name of the parent project (where all of the other human-written docs for the whole project happen to be), or in a new src/site/markdown directory created within the subproject. A file with any other non-special name can be added in either place, and end up where you expect it in the target. But not for index.md, in that case only the second location can work, and even then, only after a clean.

I had tried both places without success, but trying the second again with a full clean install site site:stage makes it work. Out of the four combinations (parent/clean, parent/noclean, sub/clean, sub/noclean), that was the one I missed trying before posting the question, so of course that's the one that works. :)

If there had been an answer or comment like "hmm, are you sure an index.md in the subproject doesn't work, it works for me?" it probably would have put me quickly back on track. Sometimes after trying several avenues all without success, all that's needed is to know which of them is the one that's supposed to work (if indeed one of them is) and therefore worth spending more time on.

Chapman Flack
  • 604
  • 5
  • 13