--- title: "Quickstart" description: "Create a Beacon site with npm create beacon-docs, run the development server, write your first docs page, and deploy the site to Vercel." url: https://beacon-arodoni.vercel.app/quickstart --- # Quickstart This quickstart walks you through creating a documentation site for `MyProduct` integrated with the `my-docs` GitHub repository and deployed to Vercel. ## Requirements Before you begin, install and set up the required software and environments. ### Node.js and Node Package Manager On your local machine, install: - [Node.js](https://nodejs.org/) 20.9.0 or later, the minimum version that Next.js 16 supports - Node Package Manager (`npm`), which is bundled with Node.js ### GitHub account and repository 1. **Create the repository** On GitHub, using an existing account or a new account, [create a new repository](https://github.com/new) named `my-docs`. Leave the new repository empty. Don't add a README, `.gitignore`, or license. 2. **Configure the Vercel app** In the repository settings, click **Installed GitHub Apps**, confirm Vercel is installed, and click **Configure**. 3. **Grant repository access** In the Repository access section, select the repository you created, `my-docs`, or allow access to all repositories. ### Vercel account and project 1. **Import the repository** In Vercel, using an existing account or a new account, [import the GitHub repository](https://vercel.com/new), `my-docs`, and click **Deploy**. Leave the build settings at their defaults. Vercel detects the Next.js static export automatically. You can ignore the warning about the missing branch. 2. **Copy the domain** From the Dashboard, click the card for the new project, `my-docs`, and copy the domain that Vercel assigned to it, ``, from the **Domains** list. 3. **Set the site URL** Navigate to **Environment Variables**, add the following key and value, and click **Save**: - Key: `SITE_URL` - Value: your assigned domain, including `https://`, for example, `https://my-docs-black-chi.vercel.app` `SITE_URL` doesn't change where the site deploys. Beacon uses it to build absolute links in canonical tags, `sitemap.xml`, and `/llms.txt`. ## Install and run Beacon Install Beacon on your local machine. 1. **Create the site** Create a new site, `my-docs`: ```bash npm create beacon-docs@latest my-docs ``` When prompted, enter the project name, `my-docs`, and the product name, `MyProduct`. The command performs the following tasks: 1. Downloads Beacon. 1. Adds starter pages. 1. Saves the product name in `.env.local`. 1. Creates a local Git repository with an initial commit. 1. Installs the dependencies. 2. **Change to the project directory** ```bash cd my-docs ``` 3. **Start the development server** Start a local development server to preview your changes as you edit the content in the next section: ```bash npm run dev ``` The development server runs at [http://localhost:3000](http://localhost:3000) and renders each page when you request it, but doesn't write the site to the `out/` directory. Changes to `content/nav.config.ts` reload automatically. To see changes to `.mdx` files, refresh the browser. ## Add a documentation page 1. **Create the page file** Create a file under `content/docs/` for the new page, `content/docs/my-page.mdx`. 2. **Add frontmatter and content** In the new page, add a frontmatter block with a title and description: ```md --- title: My Page description: A short, specific summary of what this page covers. --- # My Page This is the content for MyProduct. ``` Beacon picks up the file automatically and adds it to the client-side search index. The build also adds it to the sitemap. 3. **Add the page to the navigation** In `content/nav.config.ts`, add an entry for the new file to a group's `items` array, for example, the **Get Started** group: ```ts { title: "My Page", href: "/my-page" } ``` 4. **View the page** With the development server running, open [http://localhost:3000/my-page](http://localhost:3000/my-page) to view the new page. 5. **Stop the development server** Press `Ctrl+C`. ## Push the changes to GitHub 1. **Commit the changes** On your local machine, commit the page that you added, `my-page.mdx`, and the `content/nav.config.ts` file: ```bash git add . git commit -m "Add my page" ``` 2. **Connect the remote repository** Connect your local repository to the new GitHub repository. Replace `` with your GitHub username: ```bash git remote add origin https://github.com//my-docs.git ``` 3. **Push to main** Push the changes to the `main` branch: ```bash git push -u origin main ``` In a production repository, you typically don't push directly to `main`. The quickstart does this only for simplicity. > **Tip** > > If the push fails with `Password authentication is not supported for Git operations`, GitHub rejected your account password. > > - If you've added an SSH key to your GitHub account, switch the remote to SSH by running `git remote set-url origin git@github.com:/my-docs.git`, and then push again. > > - Otherwise, when Git prompts for a password, enter a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) instead. ## Deploy to Vercel Deploy the site to Vercel to publish the new documentation. Vercel builds the site from the GitHub repository when you push to the `main` branch. 1. **Deploy the site** In the Vercel dashboard, click **Deploy**. After the first deployment, every push to `main` triggers a new production deployment, and pushes to other branches create preview deployments. 2. **View the live page** Open `https:///my-page` to view the new page. ## Clean up If you don't want to keep the quickstart project: - Delete the GitHub repository, `my-docs`. - Remove the Vercel project, `my-docs`. - Remove the local project directory, `my-docs`, from your machine.