WebHelp: background picture in "hero banner" section not loading

Post here questions and problems related to editing and publishing DITA content.
Post Reply
sopuli
Posts: 13
Joined: Fri Jul 11, 2025 2:22 pm

WebHelp: background picture in "hero banner" section not loading

Post by sopuli »

Hello again,

Working on my webhelp transformation, I ran into another problem when I tried to add a background picture to my WebHelp main page (in the "hero banner" section). For some reason, the space just stays white, however the text line I want to lay above the picture is shown in the output - so the file is working. What could be wrong with the following xhtml fragment? I double and triple checked the location of the PNG in the project folder.

Code: Select all

      .custom-hero-banner {
        position: relative;
        width: 100%;
        height: 250px; 
        background-image: url('../images/Testbackground.png'); 
        background-repeat: no-repeat;
        background-size: cover;
        background-position: center;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      .custom-hero-banner .banner-text {
        font-family: 'Oswald', sans-serif;
        font-size: 3.5em;
        color: #588bd7;
        
        text-align: center;
        padding: 0 1em;
      }
    </style>
    </head>
    <body>
        <div class="custom-hero-banner">
            <div class="banner-text">Our documentation at your fingertips</div>
        </div>
    </body>
</html>
Thank you in advance.
Best
Herdis
Top
julien_lacour
Posts: 750
Joined: Wed Oct 16, 2019 3:47 pm

Re: WebHelp: background picture in "hero banner" section not loading

Post by julien_lacour »

Hello Herdis,

I don't know what do you meant by "hero banner", so I've used webhelp.fragment.before.main.content.area.main.page in my example.
The full list is available in the manual.

The simplest solution is to copy the file in the output directory:

Code: Select all

<publishing-template>
  <name>Custom</name>
  <webhelp>       
    <resources>
      <css file="custom.css"/>
      <fileset>
        <include name="Testbackground.png"/>
      </fileset>
    </resources>
    ...
    <html-fragments>
      <fragment file="fragment.html" placeholder="webhelp.fragment.before.main.content.area.main.page"/>
    </html-fragments>
  </webhelp>
</publishing-template>
Then you just need to refer it in the fragment using background-image: url('oxygen-webhelp/template/Testbackground.png').

Regards,
Julien
Top
julien_lacour
Posts: 750
Joined: Wed Oct 16, 2019 3:47 pm

Re: WebHelp: background picture in "hero banner" section not loading

Post by julien_lacour »

It is recommended that you use the template CSS stylesheet and copy the contents of the <style> section into it. Make sure the background-image path is relative to the CSS file in this case. The advantage of this method is it works regardless of your output directory structure (if you implement another HTML fragment for your topics for example you will experience problems with relative paths). You can check this topic for all the details.

Regards,
Julien
Top
sopuli
Posts: 13
Joined: Fri Jul 11, 2025 2:22 pm

Re: WebHelp: background picture in "hero banner" section not loading

Post by sopuli »

Dear Julien,

Thank you so much for your help! I finally got around to trying this again and it worked now.
The problem was that I referenced my background picture for the html fragment in my resources folder within my template folder - not in the output folder where it will be picked up from.
The "hero banner" is what the html element is called on our website. Must be something specific. It is really just the banner section of the website.

Best wishes
Herdis
Top
Post Reply

Return to “DITA (Editing and Publishing DITA Content)”