DEV Community

Cover image for πŸ“ πŸš€ Creating our first documentation from scratch using Astro and Refact AI coding assistant
Vadim Smirnov for Refact AI

Posted on • Updated on

πŸ“ πŸš€ Creating our first documentation from scratch using Astro and Refact AI coding assistant

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.

Refact AI Repo

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
Enter fullscreen mode Exit fullscreen mode

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.

Astro starter project

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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()]
Enter fullscreen mode Exit fullscreen mode

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:

  1. We need to configure the plugin
  2. The next step will be a content collection configuration
  3. 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"
+       }
Enter fullscreen mode Exit fullscreen mode

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'
Enter fullscreen mode Exit fullscreen mode

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 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!
Enter fullscreen mode Exit fullscreen mode

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

Starlight Docs

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 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 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
  tagline: Refact is a powerful AI coding assistant that combines completion, refactoring, chat, and more.
    file: ../../assets/refact.png
    - text: Get started
      link: /getting-started/what-is-refact/
      icon: right-arrow
      variant: primary
    - text: VS Code Extension
      link: <>
    - text: Jetbrains Plugin
      link: <>

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 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 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 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.
Enter fullscreen mode Exit fullscreen mode

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

Starlight docs with custom landing page

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'
+           ]
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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


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!

Top comments (2)

nevodavid profile image
Nevo David

Great article!
Thank you for posting!

fuzzyreason profile image
Vadim Smirnov

I appreciate that!
Glad you enjoyed it!