Confluence for a public knowledge base: changing the design and customizing the division by languages

    We have six products that are used in Russia and abroad. This means that the documentation for them should be in one place, but divided into products and languages.

    We used to use MediaWiki, but over time it has become obsolete. We also expected a good layout of articles, flexible search and an internal text editor from the platform. Alternatively, choose Confluence.

    In the process, it became clear that the capabilities of this platform out of the box is also insufficient for all of our tasks. I had to purchase the Scroll Viewport plugin and spend some time setting it up.

    You can see what happened as a result , and I will tell you how I changed the design, customized the division by languages, internal search and indexing.

    Change the design

    The company began transferring documentation from the MediaWiki engine to Confluence a year ago. But when I started the project, Confluence looked standard, the previous developer added our logo and hid elements that were not needed by the anonymous user. By the launch it was necessary to bring the documentation to our style. Designers have prepared layouts, and I had to impose them. I note that Confluence is a Java application, and not a website with familiar backends and frontends. In the Appearance section, you can add a style sheet or customize custom HTML, but this is not enough for a full redesign. Therefore, for the layout we bought the Scroll Viewport plugin. This is where the fun began.

    But the fact is that Confluence itself gives very little flexibility in styles and scripts, and the possibilities out of the box are nontrivial to understand and use, and the web developer is not used to.

    Scroll Viewport Plugin

    Scroll Viewport is a plugin for Confluence that allows you to create themes using the familiar code editor and file manager. With it, you can write styles, work with page templates, add images, customize search.

    Themes are created for spaces. Spaces in Confluence are content entities that store information on a single project. We have space for products: ISPmanager, BILLmanager, etc., as well as for the main page. The space has a key, a title, a number of settings and, in fact, a theme.

    Editing a theme in Scroll Viewport: markup, styles and html

    Let's start to learn Scroll Viewport. When the plugin is installed and enabled, you need to click on the gear and then - Basic Settings - section Scroll Viewport - Themes .

    Select, copy or create a theme and click Edit . The theme editor Scroll Viewport opens.

    Please note, Scroll Viewport recommends not to create a theme from scratch, but to use Scroll WebHelp Theme as a basis.

    Scroll Viewport theme editor: on the left is the structure of the theme, on top of the file name, in the main part of the files themselves

    . Define the layout and structure of the pages, add styles and scripts, and then proceed to edit the HTML markup of the content elements.

    Markup: edit, add classes and display same type elements in a loop

    The structure of pages by type

    At the root of the theme are the main templates: page.vm, search.vm, error.vm, and also the cover image of the theme thumbnail.png.

    The template “page.vm” sets the structure of all pages of the theme. Here you can edit html and use placeholders to specify where content will be displayed. Placers refer to the content of the space or user data (the title of the material, the name of the space, the name of the author), their full list can be found in the help center of the developer Scroll Viewport .

    “Page.vm” refers to the templates that lie one level lower in the “include” folder and wraps them in tags and blocks. In this file (page.vm) we collect the page in pieces, and we supplement the markup with all the necessary attributes of the html-document. This is where we specify the doctype, prescribe the head and body.

    Components of the page

    In the folder “include” are pieces of the page. From the file names, you can guess which one is responsible for what:

    • include-htmlhead.vm contains everything that we usually specify in the head of the html document: access to style sheets, font files, some scripts, including standard Confluence and Scroll Viewport scripts;
    • include-headerbar.vm specifies the header structure;
    • include-footer.vm defines the structure of the footer;
    • include-content.vm describes the structure of the main content block;
    • include-sidebar.vm describes the layout of the side menu, which usually contains a list of all the articles in the space.

    The syntax of Scroll Viewport templates is easy to understand. Operations begin with a grid, for example “#if (condition)” or “#foreach ($ language in $ languages.available)”, and end with “#end”, inside is the operator's body. All the rest is html-tags.

    Stylization: add styles, images and scripts

    Inside the “assets” folder there are js and css files. Since we did not create a theme from scratch, there are already files from Scroll Viewport developers.

    To customize styles, it is better to create a new css-file and connect it to the head of the page template. Files that start with a theme contain the rules of the basic Scroll Viewport theme. They should be edited in the case when new styles run into the basic ones. Be careful when deleting and adding rules, remember the hierarchy of selectors, it can help out.

    I also added a folder with images and a folder with fonts to “assets”. The file manager does not work perfectly, you cannot add a folder to the desired directory, so you had to cheat. I created a folder on my computer, added a file to it, and then loaded it into the desired directory with drag-and-drop. Once the folder is created, there are no problems with downloading files.

    When creating a new design, we took into account the capabilities of the plug-in and focused on existing themes in the Scroll Viewport, so I didn’t linger for long on assets / js. Made minor changes to existing script files and added files of necessary libraries. If the changes are more significant, the scripts will have to be dealt with in more detail.

    Editor HTML markup of article content

    In the process of working with Scroll Viewport, it turned out that we can make up, but not everything. The authority of the plugin template ends with the $ page.renderContent variable. How to typeset the main elements with classes and links? Unclear. Where is HTML? By default it is not there. The variable suggests that we have to perform part of the layout directly on the article page, however, while only text can be edited there, but not tags.

    Fortunately, you can always search for plugins, and, what luck, the right one was found almost immediately. This is the Confluence Source Editor. After installing it, you can also do some good old hypertext in the article editing mode. Finally!

    Source Editor Plugin

    In the Scroll Viewport typeset the cap, sidebar, footer and set the styles. Content typeset using Source Editor. In total, I created two topics: for article pages and for the main documentation page.

    Viewport space settings: apply theme

    When a theme is created, it must be associated with space. To do this, you need to create a viewport in the space settings. Viewport is what connects space and theme. Only by creating this entity, you can apply theme styles to the space.

    Enter the space of the desired product, open Space Settings - Add-ons . Here you can create a Viewport and manage it: set themes, content types, permissions, domain and path.

    Form to link the space with the theme, create a viewport

    Choose a topic

    The Themes tab shows all created themes and one default theme that appears with the Scroll Viewport plugin. Select a theme and apply to the space.

    The Content tab allows you to select the type of content to which the theme will be applied. It is least interesting to us, as the key of space pulls in automatically.

    Configure addresses

    On the URL tab, you can select the domain and the path where the space will be opened, as well as set the address structure. It will also be needed to separate the documentation into two domains by language.

    There are two types of URL structure:

    • multilevel - the path reflects the hierarchy of articles of space and names of pages,
    • one-level - all articles are available at the same level with numeric suffixes

    With the addresses of the pages there is a nuance. For articles in different languages, Confluence generates URLs in different ways. In English, the name is displayed in the address, and in Russian - a disconnected set of letters, symbols and numbers. Scroll Viewport allows you to bring addresses to one type. If you choose a multi-level structure, then the addresses of Russian articles will display the name of the text in transliteration.

    But you need to consider that when choosing multi-level URLs will depend on the title of the article. Change the name - will change the address of the article. If you select a single-level structure, the address will be less readable and understandable, but will no longer depend on the page title.

    We chose a multilevel type of structure and readable addresses, but we will have to monitor the change of article titles and set up redirects in time. And we are still looking for the perfect option. We also use short links that always lead to the article and do not change, such a link can be found in the section Information about the page .

    Include topic

    In the Permissions tab, you can designate which users will be able to view the space using Viewport.

    In order for anonymous users to see the documentation only in a given design, you need to put two checkmarks:

    • Restrict access to Confluence UI,
    • Automatically redirect users to viewport.

    Space view settings in the Permissions tab

    Customize the division by language

    We have documentation in English and Russian, so you need to open spaces in Russian on the domain .ru, and in English - on .com.

    In Scroll Viewport such settings are provided, but if you just enter a different domain from the main tab in the URL field in the Domain Name field , two domains will not work. This is a feature of the Scroll Viewport plugin.

    You need to set up a reverse proxy so that user requests are transmitted to Confluence and resolved to two domains there - see the Scroll Viewport instruction (configurations for Nginx and TOMCAT). After that, you must turn off co-editing mode or make additional changes . Now you can specify one of two domains in the Viewport settings.

    Themes for different languages

    Applying one theme to spaces in a different language will not work, because the theme includes not only styles, but also page templates. This means that the language of elements that are not displayed by variables does not change. For example, the text-placeholder in the search bar, contacts in the footer, etc. So I had to do separate topics for spaces in Russian and English.

    In fact, I create themes that are identical in style, but the patterns for them are different, mostly in part of the text. This is overkill and duplication, yes, but I haven’t found any other way. In addition, the topic regulates the work of the search, too, and this is another argument in favor of the division by languages.

    As a result, I got four topics: two for the main pages in Russian and English, and two more for the content pages for each language.

    Customize site search

    Search parameters are configured in files from the “include” folder. Inside them we set the search parameters:

    • include-quicksearch.vm is responsible for the search field on all pages of content,
    • include-search.vm sets the structure of pages with search results.

    Where to looking for

    By default, the search only works on the current space. For example, in the ISPmanager space - only under articles about ISPmanager. If you need to search the list of spaces, you need to specify their keys in the settings include-quicksearch.vm.

        #set($search = "/search")
        #if ($stringUtils.equals(${}, "/") == false)
            #set($search = "${}/search")
      <divclass="ht-search-input"><formaction="$search"method="GET"><inputclass="search-input"type="text"autocomplete="off"name="q"value="$!searchRequest.queryString"placeholder="Что вы ищете?"/><inputtype="hidden"name="max"value="20" /><inputtype="submit"style="display:none"value="Submit">
          ## --- START --- Scroll Versions and Scroll Translations Integration -------------------------------------------
            #if ($versions || $variants || $languages)
            ## --- END -----------------------------------------------------------------------------------------------------

    Search space for individual space

        #set($search = "/search")
        #if ($stringUtils.equals(${}, "/") == false)
            #set($search = "${}/search")
      <divclass="ht-search-input"><formaction="$search"method="GET"><inputclass="search-input"type="text"autocomplete="off"placeholder="Что вы ищете?"name="q"value="$!searchRequest.queryString" /><inputtype="hidden"name="s"value="BILLmgr" /><inputtype="hidden"name="s"value="VMKVM" /><inputtype="hidden"name="s"value="VMmgr5Cloud" /><inputtype="hidden"name="s"value="VMmgr5OVZ" /><inputtype="hidden"name="s"value="DCImgr" /><inputtype="hidden"name="s"value="IPmgr5" /><inputtype="hidden"name="s"value=" ISPmgr5BUSINESS" /><inputtype="hidden"name="s"value="ISPmgr5Lite" /><inputtype="hidden"name="s"value=" DNSmgr" /><inputtype="hidden"name="s"value=" COREmgr" /><inputtype="hidden"name="max"value="20" /><inputtype="submit"style="display:none"value="Submit">
          ## --- START --- Scroll Versions and Scroll Translations Integration -------------------------------------------
            #if ($versions || $variants || $languages)
            ## --- END -----------------------------------------------------------------------------------------------------

    Space Search Form

    How to display the results

    How the list with search results will look like, specifies the include-search.vm template. In my case, each found link has a title, description, and the name of the space to which the article belongs. Here you can specify what the user will see if the search does not find anything.

    From the template fragment below it can be seen that the search results are displayed in a loop using placeholder variables. Search results can be quite a lot, so at the bottom of the page did pagination. A detailed guide to search page templates can be found in the Scroll Viewport search documentation .

               #if ($ > 0)
                #foreach($result in $searchResults.items)
                      #set( $space = '' )
                      #if( $result.type == 'page' )
                         #set( $space = $result.getObject().fromConfluence.getSpace().getName() )
                           #if( $space )
                <h4>Мы ничего не нашли :(</h4><p>Проверьте запрос на ошибки, измените его или воспользуйтесь содержанием.</p>
                #foreach ($pagerPage in $pager.pages)
                  #if ($pagerPage.current)

    What does the search page look like?

    In the “search.vm” template, the entire structure of the search pages is set, starting from the opening tag. In this template you should put together a search form and its results. As a result, we get a page like “search”, which includes the search form and the found matches, divided into several pages.

    All first-level templates located in the structure next to page.vm override the page structure depending on its type. So search.vm sets the layout of search pages, and error.vm sets error pages.

    It remains to set styles for elements, it is possible to add scripts, and our theme becomes functional, performs tasks and looks according to the design.

    Customize indexing

    To set up indexing, you need to put a sitemap in the root folder. But we do not have a root folder, because Confluence is a Java application, not a website. What to do?

    The hint was found in the Scroll Viewport documentation . Inside the space of diluting pages where the main one is stored, you need to create a new article, name it sitemap.xml and place it one level below the main one.

    The location is important because, as noted in the documentation, the map file will not be accessible to Viewport with the path prefix “/”. Just such a prefix in Viewport space of the main page.

    The sitemap.xml article in the space structure

    We remember that the article title and its URL are linked in Confluence. When the page is created and already opens at, we will deal with its correct display. Such a URL format is not quite typical, but it suits us perfectly.

    The site map should be without unnecessary tags and styles, because it is created for search engines. To prevent the previously specified styles from being applied to the site map, you need to create a include-sitemap.vm template and copy the contents of the prepared sitemap - sitemap.xml into it. It will look like this:

    Now for the sitemap.xml page, we will create a separate condition in the page.vm template, so that the styles and the structure of the templates are applied to all pages except the site map.

    For the condition you will need an identifier. You can find it out by opening the page and then clicking on Dots - Page Information , and at the end of the address bar there will be an identifier. Now we write the condition:

    #if ($ == 25370522)
    /Разметка для остальных страниц/

    After the described manipulations, the path to the site map can be specified in the panels of the Yandex and Google webmaster, and the indexing will begin.

    In general, the question of indexation remains open to me. It’s not entirely clear how the Confluence content pages are indexed. We need to think about how to automate the process.

    So it goes

    That's how I set up the design, localization, search and indexing of documentation for Confluence. It took time and the help of Scroll Viewport technical support to deal with non-obvious things. I hope my experience will be useful to those who will face a similar task.

    Also popular now: