Discover the Advanced Features on our Developers Portal
In my previous blog post, I explained why I chose Next.js and MDX to process Markdown files documenting the core features and functionalities of evitaDB and its advantages. In this article, we will take a closer look at some of the components we use to enhance developers' and users' experience.
Fueling Innovation - Brainstorming
As a developer, I regularly engage in extensive reading, whether it involves going through documentations, articles, or
any other relevant sources. Whenever I encounter a page that offers additional features, I truly value the effort put
forth by someone to present a fundamental concept. This is precisely why our focus has been directed towards crafting
easily readable pages, packed with numerous examples and captivating showcases with added interactivity.
Right from the start, I knew that we will be showcasing numerous examples of syntax in various programming languages.
Moreover, I was aware that I would need an expandable syntax highlighter to facilitate the implementation of a
custom parser for the new evitaQL syntax. To address this need, I made the strategic choice to
adopt Prism, a lightweight and highly customizable syntax highlighter with modern web standards
in mind. Currently, numerous documents are being created and updated, and the evitaQL parser is included in our
repository. As we progress towards the final stages and the growing popularity of the evitaQL language, we intend to
submit a merge request to Prism's repository.
Below is an example of basic syntax and its corresponding highlighting used.
On numerous occasions, it becomes necessary to present multiple code blocks that feature similar queries or other code
examples. Rather than displaying these code blocks one after another, we employ the use of clickable tabs to group
them together. Instead of enclosing each code block within backticks, I've created a <CodeTabs /> custom component.
Each code block is then rendered as an individual tab within the <CodeTabsBlock />.
Markup
Example of CodeTabs markup
Result
In a similar fashion, developers writing documents also have the option to display tabs with code snippets from an
external source folder. For this, I created another <SourceCodeTabs /> custom component. The UI of this component is
almost the same as the <CodeTabs /> component, but it can handle relative URLs of files or folders in the repository.
When you look at the markup below, you'll notice that it includes a Markdown link within the <SourceCodeTabs />
component. This deliberate inclusion serves the purpose of offering a fallback option to readers on GitHub. By providing
a link to the relevant source file or folder, we ensure accessibility to the showcase.
If you are working with a similar setup and your Markdown files are hosted on Github, it is crucial to ensure that you insert a new line after the opening custom tag. Alternatively, you can place the custom tag, which includes the link, on a single line.
Markup
Result
There are more features to this specific component, but I'll get to this later.
Switching programming languages to user preference
When we first saw the pages of the live documentation, we recognized an opportunity to enhance the user experience by
implementing a feature that would allow for the selective display of content based on the programming language being
used. With evitaDB it is possible to communicate in different languages and this requires the preparation of examples in
different formats. At the same time, it does not make sense to display all formats at once - the developer will probably
be interested only in the variant he intends to use during integration. However, this posed a challenge due to various
obstacles, such as page indexing and print support.
It all started with the <LS /> component. I believe that from its name and markup, you can already
understand the purpose of this component.
Markup
Now, let's move on to the next step, which involves creating a user-friendly switch to allow users to easily switch
between programming languages based on their preferences.
To tackle this task, I have chosen to implement a strategy where each custom component that interacts with the language
switch will utilize local storage to efficiently store and retrieve the user's preferred programming language.
As you can see the value is pushed to router query which results in updated URL
parameter ?codelang={preferredLanguage}. This will preserve the correct preset language in case the user copies the
link to the clipboard and sends it to someone else. This person will then get the same page variant as the person who
sent the link.
The component is now aware of preferred language. In case of <LS /> component, show the actual content
depending on your preferred programming language.
On smaller screens, you'll display the preferred language switch after clicking on the button with an anchor icon. On larger screens, you will find the preferred language switch in the top right corner of your screen.
Prefered language swich
Markup
Result
This block of text is specific to evitaql and java programming language.
To ensure comprehensive indexing of all content, I have chosen to exclusively hide any irrelevant information while
prioritizing visual accessibility, even if it leads to layout shifting. Moreover, when a user opts to print the
document, our component render function incorporates supplementary elements to enhance the visibility of this
functionality.
So when you try to print this page, you'll see that the <LS /> examples shown above are available and
ready to be printed. The print preview is similar to what you see on the Github itself, where all the content is visible
regardless.
Custom <LS /> component print example.
What's next
In the upcoming post, I will disclose our strategy for future development and outline our plan to implement features
such as document versioning, enabling users to access specific historical versions by switching to different branches.
Example of CodeTabs markup
Prefered language swich