How to create dynamic blog pages in docusaurus with strapi?

Docusaurus is an open-source static site generator specifically tailored for building, deploying, and maintaining documentation websites easily. It was created by Facebook (Meta) as part of their effort to streamline the process of creating high-quality documentation. Docusaurus is built on top of modern web technologies such as React and is designed to provide a smooth experience for both developers and technical writers.

Key Features of Docusaurus

Easy Setup: Docusaurus provides a straightforward setup process that allows you to get a documentation site up and running quickly.
Markdown Support: Content is written using Markdown, making it simple for writers and developers to contribute.
Out-of-the-box Search: Docusaurus sites come with a built-in search functionality, which improves the user experience.
Versioning: Allows you to manage documentation for multiple versions of your project easily.
Customization: You can override default themes and components using React to fit your specific design needs.
i18n: Internationalization support enabling you to offer documentation in multiple languages.
Plugins and Themes: Docusaurus supports a variety of plugins and themes to extend the functionality and appearance of your documentation site.

How to Use Docusaurus

Below is a general overview of how to get started with Docusaurus:

Install Docusaurus
You can install Docusaurus using npm or yarn. Open a terminal and run:
Copy Code
```
npx create-docusaurus@latest my-website classic
```
This creates a new Docusaurus project named "my-website" using the "classic" template.
Navigate to Your Project
Copy Code
```
cd my-website
```
Start the Development Server
You can start a local development server by running:
Copy Code
```
npm run start
```
This will start a development server, and you can see your documentation site at http://localhost:3000.
Writing Documentation
Documentation is typically placed in the docs directory, using Markdown files. For example, to create a new document, you can add a Markdown file in the docs folder:
Copy Code
```
# My New Document

This is the content of my new document.
```
Customization
You can customize the site appearance and functionality by updating the configuration file docusaurus.config.js, adding custom CSS, or creating custom React components.
Build and Deploy
Once you're satisfied with your local changes, you can build the site for production:
Copy Code
```
npm run build
```
This generates static HTML files in the build directory, which you can deploy to any static hosting service like GitHub Pages, Netlify, or Vercel.

Example of `docusaurus.config.js` Configuration

Here is a simple example of what your Docusaurus configuration might look like:

module.exports = {
  title: 'My Site',
  tagline: 'Dinosaurs are cool',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          to: 'docs/',
          activeBasePath: 'docs',
          label: 'Docs',
          position: 'left',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
        {
          href: 'https://github.com/facebook/docusaurus',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
  },
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        blog: {
          showReadingTime: true,
        },
      },
    ],
  ],
};

This configuration sets the title, base URL, and other settings for your Docusaurus site and specifies how the documentation and blog features are configured.

What is Strapi and how is it used?

Strapi is an open-source headless Content Management System (CMS) that allows developers to build customizable and flexible APIs straightforwardly. Being a headless CMS means that it focuses solely on managing and delivering content, and it does not dictate how or where the content is displayed. This decoupling of the content management (back-end) and content presentation (front-end) allows for more flexibility in building applications.

Key Features of Strapi

User-Friendly Admin Panel: Intuitive interface for managing content, users, roles, and permissions.
Customizable API: Allows customization of the API endpoint and structure to meet specific project requirements.
Role-Based Access Control (RBAC): Secure content with granular permissions and roles.
Plugins Ecosystem: Extensible through plugins that can add additional functionality.
Localization (i18n): Handles multiple languages and localization requirements.
GraphQL Support: Comes with native support for GraphQL, in addition to RESTful APIs.
Media Library: Manages images, videos, and other media files.
Customizable Content Types: Design custom content types with an intuitive content type builder.

How to Use Strapi

Here is an overview of how to get started with Strapi:

Install Strapi
You can quickly scaffold a new Strapi project using npm or yarn. Open your terminal and run:
```
npx create-strapi-app my-project --quickstart
```
This command will create a new Strapi project named "my-project" and start it using the default quickstart settings (SQLite as the default database).
Navigate to Your Project
Copy Code
```
cd my-project
```
Start the Strapi Server
Start the development server by running:
```
npm run develop
```
This will start the Strapi server, and you can access the admin panel at http://localhost:1337/admin.
Set Up Your Admin User
The first time you visit the admin panel, you will be prompted to create an admin user. Follow the on-screen instructions to complete the setup.
Creating Content Types
Inside the admin panel, you can define new content types. Navigate to "Content-Types Builder," click on "Create new collection type," and add fields as needed. For example, to create a blog post content type with fields like title, content, and published_at, follow the prompts to add these fields.
Adding Content
After defining the content types, you can start creating content items. Navigate to the content type you created (e.g., "Blog posts") and click "Create new entry" to add a new post.
Accessing API Endpoints
By default, Strapi exposes RESTful API endpoints for your content types. For example, if you created a "Blog posts" content type, you can access it via:
```
http://localhost:1337/api/blog-posts
```
If GraphQL is enabled, you can access the GraphQL playground at:
```
http://localhost:1337/graphql
```
Deploying Strapi
When you're ready to deploy Strapi, you can host it on various platforms like Heroku, DigitalOcean, AWS, and others. You need to build the admin panel for production before deploying:
```
npm run build
```
Then follow the hosting provider's instructions to deploy your application.

Example: Custom Content Type Setup

Here’s a quick example of creating a custom content type for "Articles":

Create Content Type: Navigate to Content-Type Builder, click on “Create new collection type,” and name it "Article”.
Add Fields:
- Add a Text field named "Title".
- Add a Rich Text field named "Content".
- Add a Date field named "Published Date".
Save and Create Entries: Save the content type and navigate to "Articles" in the admin sidebar. Click on "Create new entry" to add new articles.
Consume Content via API:
- To list all articles: GET http://localhost:1337/api/articles
- To get a single article by ID: GET http://localhost:1337/api/articles/:id

How to create static and dynamic pages in Docusaurus?

To grasp how pages are generated in Docusaurus, it's important to recognize that Docusaurus itself and its core features are essentially built using plugins. In simple terms, a plugin is a function that returns an object containing callbacks, with each callback running at specific points in the content generation process.

In order to understand page generation, you can read and analyze the source code of Docusaurus's blog content generation plugin. The key callback to focus on is loadContent(), which is responsible for loading the content and metadata for each page.

Once all the pages are loaded, the contentLoaded() callback is triggered. This function takes the array of page data produced by loadContent() and proceeds to create one or more pages. The contentLoaded function accepts an object as its argument, with two particularly important keys: content and actions.

content: This contains the data from the previous loadContent step and can be of any type. For instance, you could return an object with multiple keys from loadContent.
actions: This is an object with functions that dictate what Docusaurus should do next. A crucial function here is actions.addRoute(...), which is used to create a new file that will be served at a specified route path.

For a complete understanding, refer to the full documentation on the plugin lifecycle. However, the APIs mentioned above are the essentials needed to achieve our goal.

Create Strapi Page Generate Plugin

Let's navigate to our docusaurus.config.js and update our plugins key:

// docusaurus.config.js

 plugins: [
 	...
    [
      "./plugins/strapi-page-generate.js",
      {
      	//custom data to send into strapi-page-generate.js plugin
      }
      
    ],
    ...
]

In strapi-page-generate.js add following code blocks;

// strapi-page-generate.js

async function strapiPageGenerate(context, options) {
      return {
        // a unique name for this plugin
        name: "strapi-page-generate",
        // lifecycle callback
        async loadContent() {
          // we can make some async/await API calls here
          // or load data from a database
          return {blogs: "data"} ;
        },
        // lifecycle callback
        async contentLoaded({ content, actions }) {
          const {blogs}  = content
          // optional: use Promise.all to execute multiple async functions at once
          // this will speed things up by creating pages in parallel
          await Promise.all(
            prompts.map(async (prompt) => {
              return actions.addRoute({
                // this is the path slug
                path: "/blog",
                // the page component used to render the page
                component: require.resolve( "./src/myBlogs.tsx"),
                // will only match for exactly matching paths
                exact: true,
                // you can use this to optionally overwrite certain theme components
                
                modules: {},
                // any extra custom data keys are passed to the page
                customData: content
              });
            })
          );
        },
  // ...

You can use the code above as a foundation for creating your custom Docusaurus page.

Let's break it down step by step:

Unique Plugin Name: Every plugin must have a unique name to avoid conflicts with other plugins.
Loading Content with loadContent(): This callback is used to load data that your plugin will utilize. For instance, the plugin-content-blog reads files from the filesystem, but you can load data from any source you prefer.
Processing Data with contentLoaded(): This callback processes the data loaded by loadContent() and turns it into different routes. Each route requires a RouteConfig which determines what gets written to the filesystem during the build. It also specifies which components will be used to render the page, and allows for theme component modules to be overridden. Here, you'll also set the page slug, which will become the file path of the generated page.
Creating a Page Component: Make sure you have a file named src/myBlogs.tsx. This file will render your custom page, and Docusaurus will use it to statically export your React component as a page.

By following these steps, you can create and configure custom pages in Docusaurus efficiently.

Share on social media:

Tags:

Development Tools