CUE and Us teamed up to create a new, open-source website for CUE using the Hugo framework. The website includes documentation, a playground, and a search tool. It’s currently in alpha, and both Us and CUE are working on launching it as the main website.
The collaboration with CUE was extra interesting for us because we had a high-level technical collaboration with the client. Expertise and knowledge from both sides were used to achieve the end result.
what is CUE & CUE lang?
CUE is an open-source data validation language and inference engine that is based on logic programming. While it is not a general-purpose programming language, it can be used for a variety of tasks, such as data validation, data templating, configuration, querying, code generation, and scripting. The inference engine can be used to validate data in code or as part of a code generation pipeline.
One of the key features that sets CUE apart from other languages is that it merges types and values into a single concept. In most languages, types and values are strictly distinct, but in CUE, they are ordered in a single hierarchy (a lattice). This is a powerful concept that allows CUE to do many things. It also simplifies matters. For instance, there is no need for generics and enums, sum types and null coalescing are all the same thing.
Overall, CUE is a powerful language that can be used for a variety of tasks. It is simple to use and has a number of features that make it stand out from other languages.
CUE contacted Us to help create a new website for cuelang.org and to develop solutions for displaying their content (documentation, blogs, etc.) in a way that is understandable to their target audience and makes their documentation easy to find. We also helped redesign the CUE playground, where developers can experiment with the CUE language.
Open Source
CUE is an open source project, which means its code is publicly available and can be viewed and modified by anyone via Github. CUE has a large community that uses and contributes to the language. Users can contribute code, suggestions, and bug reports via GitHub, and ask other community members questions via a public Slack channel. For the website, this meant that the code would also be open source. This was a new experience for us, as all of our previous projects had used private repositories. Also it was very interesting here that the community also has a say in the direction CUE is going and the solutions needed for it.
For Us this was a very good learning experience. Not only is our code for the project now public, but the working method is also more structured and organized than we are used to. For instance, commit messages must adhere to certain rules. They must clearly describe what was done for the issue, what the original bugreport or story was, how to test it, and so on. Of course we also strived to achieve this goal in our other projects, but here it was even more important to formulate the commit message as clearly as possible.
A new approach we adopted was making one commit per pull request. This forced us to create more concise stories/issues and also work more with git rebase and git squash. This approach resulted in structured and clear commits which made the git history very clear and easy to understand. This is also important for CUE (and other open source projects) since changelogs can easily be created from the commit history in this way. We definitely want to incorporate this structured way of working into our other projects at Us.
Working together with the client
Another distinction between CUE and other clients is that CUE is a very technical client. For other clients, the code and the solution are less important, and the focus is mainly on design and user-friendliness. The code solutions are mainly viewed and assessed internally, and the client is presented with the endresult. This was different for this client, because we worked much more closely together on the code itself.
We used the Hugo framework for this project, which is a static site generator written in Go. This framework uses Markdown for content and Go templates for HTML. It not only generates static pages making it very fast, but also allows for custom shortcode components that work via Markdown. This allowed us to easily create the blocks needed to display the content the way we wanted. Whe chose this framework because both the Us developers and the CUE developers are familiar with it, we have developed previous projects with it and they have a background in the Go language. While most of our clients prefer a CMS to enter their content, this client is very comfortable with writing Markdown, since they are developers themselves.
We worked together with the CUE developers and a designer to come up with solutions for the different types of content. The code was checked internally and by the client. The importance of the commit message is also relevant here because, even though we and the client are both developers, we work on different parts of the site and in different coding languages. It was therefore important to clearly describe what a feature entailed and how to test it so that we could check and test each other’s code.
The CUE developers also created a preprocessor that processes the content, checks if the code examples in the documentation are still correct with the latest version of CUE, and then outputs the markdown that Hugo expects. For each Markdown piece or shortcode that we created, we made example pages that documented the options and showed how the blocks look. This was not just to test a new feature; it was also important for the configuration of the preprocessor.
Another good example of our close collaboration is the CUE playground, where developers can experiment with the CUE language. We were in charge of the UX and design implementation of the front-end, while the CUE team connected the dots on the other side, so that people could see the results of their code directly in the browser using WebAssembly.
Documentation
The documentation pages are the most important pages on the CUElang website. They are designed to be clear and easy to use for all types of developers, providing tutorials, how-to guides, and reference docs. To make the documentation as clear as possible, a number of components were created, such as code-tabs, which allow for more advanced code examples with input, data, and output.
We also created components to visualize steps in a guide, components to highlight important pieces of content, diagram components (mermaid, GoAT), column components to display content side-by-side, and more. Another important thing we introduced is a tagging system. Tags make it easy to link to related content. The sidebar navigation is also an important part of the documentation pages, as it allows users to easily find the content they are looking for.
Because it’s an open source project where the community is involved in contributing to the documentation as well, it was also important to show their involvement. For this we added authors to the pages where you can see the people involved in writing a piece of content and from there you can also visit their github pages.
Search
While creating documentation pages, it became clear that the search page would be one of the most important features of the website. The search tool must guide users to the right content in a clear way. Users should not only be able to type in search terms, but also be able to filter by content types and tags. We used Algolia to facilitate this. Algolia is an API-based search platform. All pages are indexed in Algolia, and the search API is used to get relevant search results. An advantage of using Algolia is that you are free to define your own record structure. This way, we could fine-tune our results on the searchable attributes we defined, such as content type, tag, title, content, etc.
We also used Algolia Faceting to be able to filter by properties. Filters can be used in the front-end by using dropdowns or by typing them in the search bar (e.g. tag:JSON). The search tool is also available as a component that can be used on documentation overview pages. By pre-selecting filters like content type, we can make the component relevant to the page it is used on.
Playground
In the CUE playground people can play around with cuelang. For the new website we updated the design and functionality of the playground. It’s now possible to switch between workspaces so you can work with CUE in different modes. It’s also possible to share your code: a feature which is heavily used by the community members to help each other understand CUE and solve problems. The playground is also going to be used to show examples so people can see pieces of code from the docs working in real life and also be able to play around with them.
The CUE playground is a place where people can experiment with the cuelang programming language. The new website features an updated design and functionality, including the ability to switch between workspaces and share code. The sharing feature is a valuable asset for the community, as it allows members to help each other learn and solve problems. The playground will also be used to showcase examples of code from the documentation, so that people can see how it works in real life and play around with it. We collaborated with the CUE developers to accomplish this redesign and implementation. We created the front-end of the tool using React, while CUE is responsible for the webassembly part, the database where the shared code is saved, and the example content.
Future
We’re currently working on launching the Alpha website to become the main platform. However, this does not mean that our collaboration will end there, as we have more features that we want to add to the website. Additionally, community input will help us determine our next steps.