Vadim Smirnov for Refact AI

Posted on Sep 18, 2023 • Updated on Sep 20, 2023

📝 🚀 Creating our first documentation from scratch using Astro and Refact AI coding assistant

#ai #javascript #astro #documentation

At Refact, we put performance and developer experience as our top priority. That's why we were looking for a lightweight and highly customizable template for our documentation.

Previously, we used Astro for our refact.ai website and wanted to stay within the Astro ecosystem for the documentation.

Let's see how easy it will be to build the docs using the Starlight template from Astro with the help of the Refact AI coding assistant.

Refact: Open-source AI coding assistant

Just a quick background about us: Refact is an open-source AI coding assistant that can significantly boost developer productivity with tools like code completion, code refactoring, and chat.

Building the Starlight docs

Starlight is a framework-agnostic Astro template for building documentation websites. With a straightforward configuration process and the support of Markdown and MDX, you get a solid foundation for your documentation.

In this article, we will follow the manual setup process to get a better understanding of all of the parts that are required for Starlight to work.

Creating an Astro project

First, we must create an Astro project as a foundation since Starlight is built on top of Astro.

To do that, we need to run the following command in your terminal:

npm create astro@latest

You can pick the option with the sample files.

Once the setup process is completed, you can run npm run dev in your terminal and see a starter template in your browser.

With Astro, you get an extremely straightforward structure of the project:

/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   │   └── Card.astro
│   ├── layouts/
│   │   └── Layout.astro
│   └── pages/
│       └── index.astro
└── astro.config.mjs

Adding Starlight

Now that we have the foundation, we are ready to add Starlight to turn our website into a fully functional documentation.

To do that, run the following command in your terminal:

npx astro add starlight

After completing the multistep installation process in your terminal, we can see that our Astro configuration file was updated.

import { defineConfig } from 'astro/config';

+ import starlight from "@astrojs/starlight";

export default defineConfig({
+   integrations: [starlight()]
});

Perfect! Now, we have an Astro project with a Starlight integration.

Configuring Starlight

Even though we installed the Starlight integration, we need to complete three more steps to see it working:

We need to configure the plugin
The next step will be a content collection configuration
And last but not least, we need to add markdown files to see the complete documentation

This process is very straightforward, but Refact will help us to boost the configuration process with the autocomplete functionality.

First, let's configure the plugin. Starlight allows you to set many things in the configuration, but only one property is required for the plugin to function, which is a title.

In your astro.config.mjs file, you should add a title inside the Starlight integration. Refact immediately starts to help you with that!

import { defineConfig } from 'astro/config';

import starlight from "@astrojs/starlight";

export default defineConfig({
    integrations: [starlight(
+       {
+           title: "My awesome documentation"
+       }
    )]
});

The next step is to configure the content collection. The content collection allows us to handle the dynamic generation of pages from markdown files.

To configure the content collection, we need to complete the following steps:

Create a folder structure for the documentation
Create the config file and define the collection with the docs schema

For documentation to function, we need to create a content folder inside the src directory, which will be the root directory for the documentation-specific files.

Inside that folder, we need to create the config.ts file to define the collection.

First, let's import two functions that we will use - defineCollection and doscSchema.

+ import { defineCollection } from 'astro:content'
+ import { docsSchema } from '@astrojs/starlight/schema'

Now, we are ready to define the collection. Refact will pick it up and help you to complete that logic, which speeds up the process for you and helps you with guidance on what needs to be completed

When the configuration process is completed, let's add content to see the documentation in action.

Inside the content folder, we need to add the docs directory. There, we should add an index.md file with the following structure:

---
title: "My Documentation"
description: "This is a getting started guide of my documentation."
---

This is the first segment of my documentation!

If we start the project locally, we will see our beautiful documentation functioning as expected!

Customizing your documentation

The results that we achieved are great, but it looks very generic. That's why Starlight allows you to customize the documentation and make it more personalized.

Let's modify the frontmatter in index.md file to turn it into a landing page of your documentation. Plenty of options are available for you to make a great-looking landing page. At Refact, we used the following:

template - allows you to turn a regular documentation page into a landing page
hero - an option with tagline, image, and actions properties to generate a hero banner

In addition to that, Starlight comes with components that allow you to add more code to the landing page.

Don't forget to change your index.md to index.mdx for components to work!

As a final result, here's how the code for the landing page might look:

---
title: Welcome to Refact Documentation!
description: Refact is a powerful AI coding assistant that combines completion, refactoring, chat, and more.
template: splash
hero:
  tagline: Refact is a powerful AI coding assistant that combines completion, refactoring, chat, and more.
  image:
    file: ../../assets/refact.png
  actions:
    - text: Get started
      link: /getting-started/what-is-refact/
      icon: right-arrow
      variant: primary
    - text: VS Code Extension
      link: <https://marketplace.visualstudio.com/items?itemName=smallcloud.codify>
    - text: Jetbrains Plugin
      link: <https://plugins.jetbrains.com/plugin/20647-codify>
---

import { Card, CardGrid } from '@astrojs/starlight/components';

## Features

<CardGrid stagger>
    <Card title="Code Completion" icon="pencil">
        As you write code, Refact suggests potential code completions based on the context of your code,
    looking up and down. It can suggest whole functions, classes, commonly used programming patterns,
    libraries, and APIs usage.
    </Card>
    <Card title="Improve code" icon="magnifier">
        Refact can identify code that could be refactored to be more efficient or easier to understand.
    It can also detect bugs in your code and generate patches to fix them.
    </Card>
    <Card title="AI Chat" icon="rocket">
        Use plain language prompts in Refact chat to ask questions or get help with
    writing code without leaving your IDE.
    </Card>
    <Card title="Transform and analyze code" icon="setting">
        Refact can analyze the complexity of your code and explain unclear lines of code.
    It can also transform your code into a different language.
    </Card>
</CardGrid>

The following code generated a great-looking landing page with lots of helpful content.

Changing the color theme

As you saw in the screenshot, the color theme we use for the Refact documentation differs from the one available out of the box. Starlight makes it very straightforward to change the color scheme.

Starlight allows you to add custom styles to match the documentation colors with colors that represent your brand.

First, we must create a custom.css file in the src/styles folder. After that, we must link that file to the astro.config.mjs file.

import { defineConfig } from 'astro/config';

import starlight from "@astrojs/starlight";

export default defineConfig({
    integrations: [Starlight (
        {
            title: "My awesome documentation",
+           customCss: [
+               './src/styles/custom.css'
+           ]
        }
    )
    ]
});

You can modify the color theme in your newly created CSS file. Here is an example of styles that we use at Refact to match our brand colors:

/* Dark mode colors. */
:root {
--sl-color-accent-low: #42100e;
--sl-color-accent: #c70016;
--sl-color-accent-high: #f8b6ad;
--sl-color-white: #ffffff;
--sl-color-gray-1: #eeeeee;
--sl-color-gray-2: #c2c2c2;
--sl-color-gray-3: #8b8b8b;
--sl-color-gray-4: #585858;
--sl-color-gray-5: #383838;
--sl-color-gray-6: #272727;
--sl-color-black: #181818;
}

/* Light mode colors. */
:root[data-theme='light'] {
--sl-color-accent-low: #fcc9c2;
--sl-color-accent: #cb0017;
--sl-color-accent-high: #610b0c;
--sl-color-white: #181818;
--sl-color-gray-1: #272727;
--sl-color-gray-2: #383838;
--sl-color-gray-3: #585858;
--sl-color-gray-4: #8b8b8b;
--sl-color-gray-5: #c2c2c2;
--sl-color-gray-6: #eeeeee;
--sl-color-gray-7: #f6f6f6;
--sl-color-black: #ffffff;
}

If you refresh the page, you can see that the color theme was updated!

Conclusion

And there we have it!
We've explored the Starlight project - a fantastic solution for the documentation, and we used Refact - an AI coding assistant that immediately picked up our project's context and helped us get used to an unfamiliar code base a lot faster.

Next Steps

With a solid foundation and an incredible AI ally, you can explore the Starlight project to see how to personalize and make your documentation stunning.
In addition, I encourage you to try Refact and see how it will improve your productivity and help you become more efficient as an engineer.

Join our Discord server if you need assistance from the Refact team and community to get started faster!