You all know that DXA comes with a white label HTML design based on Twitter Bootstrap, which you can style according to our own wishes and then publish these changes via the CMS. In this article I will discuss the reasoning behind all of this, and also the different options you have in case you want to change it.

Let us start with the beginning, for DXA we wanted to deliver a production ready website out of the box, that automatically means we needed HTML and an HTML design (i.e. CSS styling and some JavaScript functionality to accompany it with). So we choose a whitelabel HTML design, created especially for us, and since we wanted the HTML to be fixed we choose for a proven framework, namely Bootstrap. You can find the sources of our HTML design on GitHub and you can see an example of the built whitelabel design here: http://sdl.github.io/dxa-html-design/ (both are also available in the DXA downloads on https://appstore.sdl.com/web-content-management/list/digital-experience-accelerator/).

Now the reasoning for having HTML out of the box available, and not letting you pick and choose your own was simple. If we create a module on top of DXA, we want it to work, out of the box, simple install and just work. That means we need to supply you with HTML. Does this mean you are stuck with what we deliver? Absolutely not, you still have every option to change this, but when you do, that means a little less acceleration when you install one of the new modules. Since then you might also need to modify the HTML in the views of that module when you want to use it.

The official DXA documentation has a complete topic on the HTML design, http://docs.sdl.com/LiveContent/content/en-US/SDL%20DXA-v2/GUID-77D92E01-F6CD-45E7-A0C9-776F600364EE. This explains you all about how you can change the styling and even how you can completely swap out the HTML design with your own. But all of this assumes you are still sticking with the Bootstrap HTML, since it does not discuss anything about the HTML in the views.

So having the HTML design assets in the CMS and allowing you to modify them via the Bootstrap Configuration Component, or even by swapping out the raw assets completely in the html-design.zip is a nice feature on most demo and development environments, but I can see that this might introduce a serious risk on a production environment. Which is yet another reason why you might want to ditch this process, and make the HTML design a part of your web application and deploy it together with that.

For a while now, I have a story on the backlog that would allow you to easily remove the complete HTML design from the CMS, and allow you to build your own. But because there are other stories that have a higher priority (like adding SDL Web 8 support in our current sprints), this story keeps getting pushed to the back. I'll use this article as a guide for you, in case you want to do it anyways, so you are not impacted by the fact my story does not have enough priority to make it in the next release.

How the HTML design currently works is quite simple, we have all the raw assets for building a Bootstrap based website in our html-design.zip file. This is built via node.js and Grunt through a Template Building Block at publishing time (which simply executes the node command to let Grunt build it as instructed via the package.json and Gruntfile.js). Now because we don't care about the HTML that comes out of the Grunt build, but only need the CSS, fonts and JavaScript, we use a separate package.json and Gruntfile.js, and also we don't want the publisher to have to download all the node dependencies, so we have included all these additional files (with node.js itself) in our build-files.zip. If you want to know more details about the build process, I recommend you take a look at the source code of the Publish HTML Design TBB in GitHub.

So what do we need to do if we want to remove the HTML design build process from the CMS?

1. delete the Publish HTML Design Page (you can also delete the Component on it and its references, but simply unpublishing and deleting this page, makes the HTML design unavailable from the Broker database).
2. deploy a version.json file to the /system/assets folder of your Web application, which contains the version number which is added to the URLs for static assets, i.e.: {"version":"v0.1"}
3. deploy your CSS, fonts and JavaScript files to the to the /system/assets folder (as part of the deploy of the web application with its views)
4. update the views in case you need the HTML to be non Bootstrap

Note step #2 is very important, this is also something which comes up when people forget to publish the HTML design initially and find out DXA does not work without a version.json. The /system/assets folder is versions through the value inside the version.json file to prevent unwanted browser caching of our design assets when we update the HTML design. So keep in mind that when you deploy your HTML design manually, you will have to update the version string in the version.json file for it to become available direct without client caching issues.

I hope this article gives you more insight and I wish you all a merry x-mas!