How to manage highly customizable websites at scale?


Imagine that you need to manage customizable websites for your customers. Maybe you’re a web agency accepting all kinds of projects, or you sell a platform backing sites of a specific business.

For example, a company named Hostme ( offers restaurants a table management solution: guests can reserve a table, specify their preferences, mention allergy concerns, order high-chair for their infants, etc. The restaurant owners, on the other hand, can handle all the bookings, plan the seating schedule, manage loyalty program and do many other things. All this happens through the easily embeddable widgets that anyone (signed up with the platform) can place on their websites.

And now, Hostme would like to go beyond widgets and extend their offering by allowing customers (a restaurant or café owners), in a few clicks, instantiate a website, using one of the pre-designed templates with all the mentioned reservation widgets in it, configure them, adjust some styling (to reflect their brand), create the menu and start accepting bookings online. Surely, Hostme would take care of all the website maintenance, scaling, etc.

Of course, at some point, Hostme will need to make a change or two to some of their widgets, and while rolling the update, it is critically important not to break a customer’s customized website (or worse, thousands of those websites). If not careful, any modification to HTML markup, CSS or JavaScript of a widget may turn into unexpected outcomes on someone’s landing page, blog post, or any other content, negatively impacting their business.

Here’s a simple hypothetical example: one of the restaurant managers increased websites font size from 15px to 20px, another client has set it to 32px, third one completely replaced the font (bringing all the new characteristics to it), and on top of that Hostme, for the next release, decided to double padding of their widgets and make the text yellow and bold. What is going to be the final result for all three websites? No one knows, right?

So, what can be done about it? How can we safely update a large number of customized websites without fear to screw anyone up?

One of the solutions that experts could recommend is to separate data from its presentation (and that’s great advice). For example, you could use Markdown ( — a special language for defining rich-text content that can later be transformed into, e.g. HTML markup (or even an entire website). Thus, if you ask your customers to author the content in Markdown, you can always be sure that the resulting content will look as you expect, because you decide how exactly it renders.

There is one problem with Markdown though — it is designed to work just with the text, which does not give enough control for highly customized websites meant to reflect the brand of a business. No doubt, people would want to change component styles (buttons, pictures, menus, etc.), page layouts, responsive grids behavior, apply animations, states, and many many other things.

So, here at Paperbits, we came up with the format that describes all the above concepts in the form of a well-structured JSON document:


It gives us (and our customers like Hostme) the full control over content rendering and, at the same time, brings the end-user almost endless options for website customizations. Thus, our clients own the data, and we own the presentation, always separate from each other, and we never afraid to make updates to our codebase.

Of course, authoring the content in plain JSON is not a super convenient job for humans to do. That is why we created the visual content builder and styling tools that allow even non-skilled users to create pretty sophisticated, responsive websites (see how it works at


As you could have guessed, there are caveats with this approach as well. Just like the Markdown has its limitations over text (i.e. you cannot tell it that first letter on the page should be large (a “drop cap”)), that JSON definition does not account for every possible styling variant. You can try to eliminate the gap by bringing more configurations, but eventually, you’ve got to stick to some rules and limitation anyways, and decide what is allowed to your users and what is not (if you want to stay in control of rendering of course).

For example, to solve the hypothetical problem mentioned above, you may decide that you don’t ever change any component / element / font sizes or colors, keeping all that as user-defined data, and constrain yourself to just updating your widget behaviors (the code).

Therefore, it is always a trade-off — the more control you give, the harder your work becomes to keep track of all this. However, with the well-defined rules, feature planning and a proper testing system in place, you can offer your customers great customization options.

Stay in touch
Do you like it?
Star on Github

Copyright © 2022 Paperbits LLC. All rights reserved.