• Getting started
  • Installation
  • Running generation scripts
    • Applying JSON schema to a Yaml file
  • Configuring Tailwind
  • Integration in Nodoku skin Yaml file
• Component's default theme
• Nodoku skin component customization
  • Customization of sequential components
• Applying the Flowbite theme
• The nodoku-flowbite components
  • flowbite/card
  • flowbite/horizontal-card
  • flowbite/jumbotron
  • flowbite/carousel

nodoku-flowbite is a set of visual components to be used with the Nodoku static site generator.

The components provided in the nodoku-flowbite library are based on flowbite and flowbite-react.

The components in the nodoku-flowbite library are styled using Tailwind CSS.

All the Nodoku components support localization out of the box.

One needs to provide the i18n provider parameter to the Nodoku root component - RenderingPage.

See nodoku-i18n for more details

Getting started

Installation

The installation of the nodoku-flowbite library is straightforward:

npm install nodoku-core nodoku-flowbite

Running generation scripts

Once the installation is performed, one needs to run the following scripts in order to generate the Nodoku component resolver and Nodoku skin schema.

In brief, running the scripts would consist of the following steps:

• add the scripts to the package.json file

  • "scripts": {
      "gen-component-resolver": "nodoku-gen-component-resolver",
      "gen-skin-schema": "nodoku-gen-skin-schema"
    },

• run the scripts as follows:

  • ./gen-component-resolver
    ./gen-skin-schema

After the generation scripts are executed, the following new files should appear in the project tree:

• src/nodoku-component-resolver.ts

  • the file resolving the textual names of the components to an actual JS function implementing the compoent

• schemas/visual-schema.json

  • this JSON file is a schema to be used for Nodoku skin Yaml file.

The component resolver should be having the following lines now:

components.set("flowbite/card", { ... });
components.set("flowbite/horizontal-card", { ... });
components.set("flowbite/carousel", { ... });
components.set("flowbite/jumbotron", { ... });

Applying JSON schema to a Yaml file

There are several techniques to apply the JSON schema to a Yaml file, and they in particular depend on your development environment.

For example, this link shows the steps to follow for IntelliJ family products.

Alternatively, one can consider using the following option: add the following line to the top of the Yaml where the schema should be applied:

# yaml-language-server: $schema=../../../schemas/visual-schema.json

like this:

# yaml-language-server: $schema=../../../schemas/visual-schema.json

rows:
  - row:
      components:
        - flowbite/carousel:

Configuring Tailwind

nodoku-flowbite is a library of Nodoku visual components, based on flowbite and react-flowbite.

flowbite and react-flowbite are the libraries heavily relying on Tailwind CSS, and so is nodoku-flowibte.

Here is the Tailwind CSS config to be used with the project:

import flowbite from "flowbite-react/tailwind";
import type {Config} from "tailwindcss";

const config: Config = {
    content: [
        "./src/**/*.ts",
        "./src/**/*.tsx",
        "./src/**/*.js",
        "./src/**/*.jsx",
        "./schemas/**/*.yml",

        "./node_modules/nodoku-core/dist/esm/**/*.js",
        "./node_modules/nodoku-core/dist/esm/**/*.jsx",
        "./node_modules/nodoku-components/dist/esm/**/*.js",
        "./node_modules/nodoku-components/dist/esm/**/*.jsx",
        "./node_modules/nodoku-flowbite/dist/esm/**/*.js",
        "./node_modules/nodoku-flowbite/dist/esm/**/*.jsx",
        "./node_modules/nodoku-flowbite/dist/schemas/**/*.yml",
        "./public/**/*.html",
        "./src/**/*.{html,js}",
        "./public/site/**/*.yaml",
        flowbite.content(),
    ],
    plugins: [
        flowbite.plugin(),
    ],
};


export default config;

The main point behind this config is to make the Tailwind plugin to scan all the places where the Tailwind classnames can potentially be encountered.

This includes not only the .js/.jsx files that the bundle contains, but also the Yaml files that the bundle brings in, as the Yaml files contain the default theme configuration of a bundle in terms of Tailwind classes.

Let's have a closer look at the paths contained in the Tailwind config:

• ./src/**/*(.ts|.tsx|.js|.jsx)

  • these are the files that belong to your project. They should be scanned only if they use Tailwind themselves

• ./schemas/**/*.yml

  • after the skin schema generation (see Nodoku skin schema) this folder would contain not only the JSON schema for the Nodoku skin Yaml file (schemas/visual-schema.json), but also the default themes for the components, contained in the plugged in bundles (such as nodoku-flowbite). This folder should be included because otherwise all the default values for the component themes wouldn't be scanned, and the CSS for them wouldn't be generated by Tailwind.

• ./node_modules/nodoku-flowbite/dist/esm/**/*(.js|.jsx)

  • the components might contain some Tailwind class names in their code as well (hardcoded Tailwind classes). In order to account for them, we need to scan also the .js/.jsx files included in the component bundle. The same applies other dependencies, that might include the Tailwind classes, in particular nodoku-core and nodoku-components.

• ./public/site/**/*.yaml

  • for the sake of this example, we assume that the Nodoku skin Yaml file is being fetched from the location ./public/site. The Nodoku skin Yaml file is entirely based on Tailwind classes. Hence, it is of utmost importance to include the scanning of the Nodoku skin Yaml files to the Tailwind config.

Integration in Nodoku skin Yaml file

Use the component name in the skin Yaml file to use a given component to render a particular content block, as follows:

rows:
  - row:
      components:
        - flowbite/card:
            selector:
              attributes:
                sectionName: nodoku-way

You can find the names of the available components in the nodoku.manifest.json, found in the component bundle.

For example, for nodoku-flowbite this file should be located in:

./node-modules/nodoku-flowbite/dist/nodoku.manifest.json

Alternatively, you can look up the names of the available components in the generated ./src/nodoku-component-resolver.ts, as shown in running-generation-scripts

Make sure to apply the generated JSON schema to the skin Yaml file to facilitate the skin editing process

Component's default theme

Each component is shipped with a predefined theme file, which contains the initial settings for the given component.

For example, here is an excerpt from the default theme file for the component flowbite/card, contained in the file

./schemas/nodoku-flowbite/dist/schemas/components/card/default-theme.yml

containerStyle:
    base: w-full pb-10
    decoration: border rounded-lg shadow border-gray-200 dark:border-gray-700
...
titleStyle:
    base: mb-2 text-3xl font-bold tracking-tight
    decoration: ''
subTitleStyle:
    base: mb-2 text-2xl tracking-tight
    decoration: ''
...

This default theme file contains the necessary predefined values for different component's sections.

It is being copied to the ./schemas folder by the skin schema file generation process (gen-skin-schema script)

The file is being copied to the project folder to give a clear understand what are the default values used for the component.

Don't modify the default Yaml file to alter the component appearance. Instead, use the skin customization mechanism to fine tune the component's presentation.

For example, to add the extra top margin on the title section of the component, use:

rows
  - row:
      components:
        - flowbite/card:
            theme: 
              titleStyle: 
                decoration: mt-12
            selector:
              attributes:
                sectionName: nodoku-way

Nodoku skin component customization

The Nodoku skin file offers several level of component visual appearance customization:

• global level: the customization is applied to all the components, having the customized option (titleStyle, in this example)

global:
  theme: 
    titleStyle: 
      decoration: mt-12

• component level: the customization is applied on all the components with the given name

global:
  components:
    flowbite/card:
      theme:
        titleStyle:
          decoration: mt-12

• individual component level: the customization is applied to the given component only:

  - row:
      components:
        - flowbite/card:
            theme:
              titleStyle:
                decoration: mt-12
            selector:
              attributes:
                sectionName: nodoku-way

Customization of sequential components

Consider a situation when several components are shown in a row, and the appearance of each one of them is identical, except for a single detail, say - title color.

For example, this is a typical situation working with the card component, when several cards are displayed on a single row.

This effect can be achieved using the sequential customization.

To use this feature, instead of the attribute "theme" use the attribute "themes", which is an array of component theme structure.

This way an arbitrary number of customizations can be defined.

Each one of them will be applied sequentially on a component with the given name.

For example, consider this skin file:

rows:
  - row:
      components:
        - flowbite/card:
            themes:
              - titleStyle:
                  decoration: text-red-500
              - titleStyle:
                  decoration: text-green-500
              - titleStyle:
                  decoration: text-blue-500
            selector:
              attributes:
                sectionName: nodoku-way

The sequential customization can be applied on all the 3 levels defined above (where the single theme customization can be applied): global level, component level and individual component level.

Applying the Flowbite theme

The flowbite-react library, on top of which the nodoku-flowbite is built, allows the user to provide their own theme, which is a convenient way to customize the appearance of the flowbite-react components.

The flowbite-react theme can also be applied on the Nodoku RenderingPage component, thus customizing all the flowbite-react components, that would be used during the rendering of Nodoku.

Consider the following code:

  import {Flowbite, getTheme} from "flowbite-react";
  ...
  const customCarousel = {...getTheme()};
  
  customCarousel.carousel.scrollContainer.base = "snap-mandatory flex h-full overflow-y-hidden overflow-x-scroll scroll-smooth rounded-none";
  
  ...
  
  export default async function Home({params}: { params: { lng: string } }): Promise<JSX.Element> {
    ...  
    return (
      <Flowbite theme={{theme: customCarousel}}>
        <RenderingPage .../>
      </Flowbite>
    );
  }

In this example we are customizing the flowbite-react component Carousel, on top of which the nodoku-flowbite's component flowbite/carousel is built.

The original (default) theme for the Carousel component has the following predefined value:

const carouselTheme = createTheme({
  ...
  scrollContainer: {
    base: "flex h-full snap-mandatory overflow-y-hidden overflow-x-scroll scroll-smooth rounded-lg",
    ...
  }
});

In order to remove the class rounded-lg, and replace it the class rounded-none, to remove the rounded corners of the Carousel component, one would use the theme customization shown above.

The nodoku-flowbite components

The package nodoku-flowbite contains currently the following components.

flowbite/card

A Nodoku wrapper around the Flowbite card component:

flowbite/horizontal-card

A Nodoku wrapper around the Flowbite horizontal card component:

flowbite/jumbotron

A Nodoku wrapper around the Flowbite jumbotron component:

flowbite/carousel

A Nodoku wrapper around the Flowbite carousel component:

The Nodoku skin file can contain also the options for the nodoku/carousel components, which are the options of the underlying flowbite-react Carousel component.

For example, to customize the scroll time use the following piece of yaml code in the skin file:

  - row:
      components:
        - flowbite/carousel:
            options: 
              slideInterval: 5000
            selector:
              attributes:
                sectionName: nodoku-way

The list of available options can be found in the JSON schema file.

Alternatively, one might want to use the autocompletion option (once the schema file is correctly applied), which should look similar to this: