--- name: azion-build-with-docusaurus description: >- Create a Docusaurus site from an Azion template or the Azion CLI, and deploy it to an Azion domain. --- # Build with Docusaurus You can deploy a Docusaurus site on Azion from a template in Azion Console or with the [Azion CLI](/en/documentation/devtools/cli/). Both routes end with the site running on Azion and answering on an Azion domain. Azion runs a Docusaurus site as a static application. The build writes the site to `./build`, and the deploy uploads that folder to a storage bucket that an [application](/en/documentation/platform/applications/) serves. For the other frameworks Azion builds, refer to [Frameworks compatibility](/en/documentation/devtools/runtime/frameworks/frameworks-compatibility/). --- Select the route you will use. The prerequisites and the deploy steps below follow that choice. ## Prerequisites - An Azion account. To create one, refer to [Create an account](/en/documentation/fundamentals/creating-account/). **Console** - Access to Azion Console. To sign in, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A GitHub account. A template deploy connects it when the form asks for it. **CLI** - The Azion CLI installed and logged in. To set it up, refer to [Azion CLI quickstart](/en/documentation/devtools/cli/quickstart/). - Node.js 18 or later, and npm. - A terminal and a code editor. --- ## Docusaurus templates A template is a ready Docusaurus project that Azion deploys for you. The Console route starts from one of these templates: | Template | Use | | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | [Docusaurus JavaScript Boilerplate](/en/documentation/guides/application-development/frameworks/docusaurus-javascript-boilerplate/) | Starter project in JavaScript | | [Docusaurus TypeScript Boilerplate](/en/documentation/guides/application-development/frameworks/docusaurus-typescript-boilerplate/) | Starter project in TypeScript | Each template has a guide of its own, linked in the table. For more information on templates, refer to [Azion Marketplace](/en/documentation/platform/marketplace/). In the CLI route, `azion init` lists the same two starters as `Docusaurus Boilerplate (JS)` and `Docusaurus Boilerplate (TS)`. --- ## Deploy the site Each route builds the Docusaurus project and creates the resources that serve it on Azion. Follow the panel of the route you selected: **Console** To deploy a Docusaurus template from Azion Console: 1. **Open the templates** Access [Azion Console](https://console.azion.com/) > **Create** > **Templates**. 2. **Find the Docusaurus templates** In **Search by name, framework, or keyword**, enter `Docusaurus`. 3. **Select the template to deploy** 4. **Connect your GitHub account** If the form shows **GitHub Connection**, select **Connect with GitHub** and install the [Azion GitHub App](/en/documentation/guides/application-development/automation/azion-github-app/). 5. **Select a Git Scope** In **Git Scope**, select the scope for the template. 6. **Fill in the settings the template asks for** 7. **Select Deploy** The deploy page opens and shows the **Deploy Log** while the project builds. When the deploy succeeds, **Successfully created!** appears, and the page shows the domain URL and a **Manage** button that opens the application. **CLI** To create the project, run `azion init` with a name. In the two pickers, select *Docusaurus* and then a template: ```bash azion init --name my-site --auto -y ``` The `-y` option installs the dependencies, and `--auto` skips the questions about a local development server and a deploy. Without them, the command asks the questions that [Azion CLI init](/en/documentation/devtools/cli/init/) lists. With the *Docusaurus Boilerplate (JS)* template, the command prints: ```text ? Choose a preset: [Use arrows to move, type to filter] > AI Studio Angular Astro Docusaurus Eleventy Emscripten Gatsby Hexo Hono Hugo Javascript Jekyll Next Nuxt OpenNextJS Preact Qwik React Rustwasm Stencil Svelte Typescript Vitepress Vue Vuepress ? Choose a preset: Docusaurus ? Choose a template: [Use arrows to move, type to filter] > Docusaurus Boilerplate (JS) Docusaurus Boilerplate (TS) ? Choose a template: Docusaurus Boilerplate (JS) Fetching selected template... Template successfully fetched Template successfully configured Installing application dependencies … added 1284 packages, and audited 1285 packages in 55s 422 packages are looking for funding run `npm fund` for details 39 vulnerabilities (1 low, 3 moderate, 35 high) To address issues that do not require attention, run: npm audit fix Some issues need review, and may require choosing a different dependency. Run `npm audit` for details. … [Azion] [Build] › ℹ info Using preset: docusaurus [Azion] [Build] › ✔ success Build completed successfully with only azion.config [Azion] [IaC] › ✔ success Manifest generated successfully at /my-site/.edge/manifest.json If you want to start a local development server later, run 'azion dev' Make sure to change to the new working directory before running building or deploying your project If you want to deploy your application later, run 'azion deploy' Make sure to change to the new working directory before running building or deploying your project Your application my-site was initialized successfully ``` The command creates the project in a `my-site` folder. Its `azion.config.cjs` sets the `docusaurus` preset and uploads `./build` to a storage bucket that workloads can only read. For every setting in that file, refer to [azion.config.js](/en/documentation/devtools/cli/azion-config-js/). To build the site, change to the project folder and run `azion build`: ```bash cd my-site azion build ``` The command runs the Docusaurus build through Azion Bundler with the `docusaurus` preset, and writes the site to `build`. The Docusaurus build prints warnings about the template's configuration and blog posts, and still succeeds: ```text Building your Application. This process may take a few minutes Running build step command: $ npx --yes @aziontech/bundler@1.1.4 build --preset docusaurus … [Azion] [Build] › ℹ info Using preset: docusaurus [Azion] [Pre-Build] › ℹ info Starting pre-build... … [Docusaurus] › ℹ info > docusaurus-boilerplate-js@1.0.0 build > docusaurus build [Docusaurus] › ℹ info [WARNING] The `siteConfig.onBrokenMarkdownLinks` config option is deprecated and will be removed in Docusaurus v4. Please migrate and move this option to `siteConfig.markdown.hooks.onBrokenMarkdownLinks` instead. [Docusaurus] › ℹ info [INFO] [en] Creating an optimized production build... [Docusaurus] › ℹ info [WARNING] The `siteConfig.onBrokenMarkdownLinks` config option is deprecated and will be removed in Docusaurus v4. Please migrate and move this option to `siteConfig.markdown.hooks.onBrokenMarkdownLinks` instead. [Docusaurus] › ℹ info [WARNING] Some blog authors used in "2019-05-28-first-blog-post.md" are not defined in "authors.yml": - {"name":"Gao Wei","title":"Docusaurus Core Team","url":"https://github.com/wgao19","image_url":"https://github.com/wgao19.png","imageURL":"https://github.com/wgao19.png","socials":{},"key":null,"page":null} Note that we recommend to declare authors once in a "authors.yml" file and reference them by key in blog posts front matter to avoid author info duplication. But if you want to allow inline blog authors, you can disable this message by setting onInlineAuthors: 'ignore' in your blog plugin options. More info at https://docusaurus.io/docs/blog [Docusaurus] › ℹ info [WARNING] Docusaurus found blog posts without truncation markers: - "blog/2021-08-26-welcome/index.md" - "blog/2021-08-01-mdx-blog-post.mdx" - "blog/2019-05-28-first-blog-post.md" We recommend using truncation markers (`` or `{/* truncate */}`) in blog posts to create shorter previews on blog paginated lists. Tip: turn this security off with the `onUntruncatedBlogPosts: 'ignore'` blog plugin option. [Docusaurus] › ℹ info [webpackbar] ℹ Compiling Client [Docusaurus] › ℹ info [webpackbar] ℹ Compiling Server [Docusaurus] › ℹ info [webpackbar] ✔ Server: Compiled successfully in 4.08s [Docusaurus] › ℹ info [webpackbar] ✔ Client: Compiled successfully in 7.36s [Docusaurus] › ℹ info [SUCCESS] Generated static files in "build". [INFO] Use `npm run serve` command to test your build locally. [Azion] [Pre-Build] › ℹ info Pre-build completed successfully [Azion] [Build] › ℹ info Using built-in handler from "docusaurus" preset. [Azion] [Build] › ℹ info Starting build... [Azion] [Build] › ✔ success Build completed successfully [Azion] [Post-Build] › ℹ info Starting post-build... [Azion] [Post-Build] › ✔ success Post-build completed successfully [Azion] [Storage] › ℹ info Using provided prefix for storage '$BUCKET_NAME': $BUCKET_PREFIX [Azion] [IaC] › ✔ success Manifest generated successfully at /my-site/.edge/manifest.json Your Application was built successfully ``` To deploy the site, run `azion deploy` in the project folder: ```bash azion deploy ``` The command uploads the project and opens the Console page that follows the deploy. It also prints that page's URL in case the browser does not open. When the deploy ends, it prints the URL of the site's domain. For the full output and every flag, refer to [Azion CLI deploy](/en/documentation/devtools/cli/deploy/). To run the site on your machine before you deploy it, refer to [Azion CLI dev](/en/documentation/devtools/cli/dev-command/). To deploy a Docusaurus project that already exists, run `azion link` in its folder and select the Docusaurus preset, as [Azion CLI link](/en/documentation/devtools/cli/link-command/) describes. --- ## Check the site The deploy returns the URL of the site's Azion domain, in the form `https://xxxxxxxxxx.map.azionedge.net`. Azion Console shows it on the deploy page, and `azion deploy` prints it when it ends. Open the URL in a browser to see the Docusaurus site. The first deploy can take several minutes to answer from every location; later deploys take about two minutes. Until a location receives the site, the domain answers with a `404` page that reads `There's nothing here yet`. On that response, wait and request the URL again. --- ## Next steps - [Frameworks compatibility](/en/documentation/devtools/runtime/frameworks/frameworks-compatibility.md): Check which frameworks and presets Azion builds. - [Azion CLI deploy](/en/documentation/devtools/cli/deploy.md): Read the deploy output and the flags that change a deploy. - [Azion CLI link](/en/documentation/devtools/cli/link-command.md): Connect a Docusaurus project you already have to Azion. - [azion.config.js](/en/documentation/devtools/cli/azion-config-js.md): Change the bucket, cache, and rules the Docusaurus preset generates.