How to add custom content that only appears on your homepage

A very common situation you’ll find yourself in as a theme developer is the need to create a customization that only shows on the homepage of your community.

You might add some HTML to the “After Header” section of your theme, which will then appear on every page. You can jump through some hoops in CSS to hide this everywhere except the homepage… but instead let’s utilize the Plugin API so your content is only loaded on the homepage to begin with.

All of this can be added to the </head> (head_tag.html) section of your theme.

This first part determines which page we’re on, and shows or hides our customization accordingly:

<script type="text/discourse-plugin" version="0.8">
  // This is the plugin outlet, followed by a custom name for the component
  api.registerConnectorClass("below-site-header", "custom-homepage", {

    // Setting up our component
    setupComponent(args, component) {

     // Next we're getting the site setting 'top_menu',
     // splitting the values into an array,
     // and adding a leading slash
     var topMenuRoutes = 
        Discourse.SiteSettings.top_menu.split('|')
        .map(function(route) {return '/' + route});
      
     // The first page listed in the 'top_menu' setting is your homepage
     // lets assign it to a variable
     var homeRoute = topMenuRoutes[0];
  
     // This calls our code whenever the page changes
     api.onPageChange((url) => {

        // Check if we're on the homepage 
        if (url === "/" || url === homeRoute ){ 
          // If it's the homepage add the 'custom-homepage' class to HTML tag
          // and set 'displayCustomHomepage' to true
          document.querySelector("html").classList.add("custom-homepage"); 
          component.set("displayCustomHomepage", true); 
        } else {  
          // If we're not on the homepage remove the class
          // and set `displayCustomHomepage` to false
          document.querySelector("html").classList.remove("custom-homepage"); 
          component.set("displayCustomHomepage", false); 
        }
      });
    }
    
  });

</script>

The second part is your handlebars template. This is where you put your custom HTML. Note how the script tag references the relevant plugin outlet and the custom component name set above.

<script type="text/x-handlebars" data-template-name="/connectors/below-site-header/custom-homepage">
  {{#if displayCustomHomepage}} 
    <div class="custom-homepage-wrapper wrap">
       <!-- This div with the class "wrap" will match the max-width
            of Discourse's content. If you want your content to be the 
            full browser width you can remove the div. 
       <!-- Your HTML here -->
    </div>
  {{/if}}
</script>

So now you have custom HTML that only appears on your homepage. The above script also added the class custom-homepage to the HTML tag on your homepage, so you can also easily apply homepage-specific CSS styling.

.custom-homepage {
  // Your styles here
}

If you’re looking to use this to add a banner to your homepage, here’s some CSS to start with that will get your content positioned correctly

Homepage banner positioning
.custom-homepage {
  #main-outlet {
    padding-top: 0;
   }
  .below-site-header-outlet {
    padding-top: 6em;
  }
}

If you want to learn more about the topics covered in this example or see what else you can do with the Plugin API, check out our Developer’s guide to Discourse Themes

19 Likes