posthtml-bootstrap

A PostHTML plugin that allows you to use Bootstrap components directly in your HTML code.

Install

To get started, install the package using npm or yarn:

npm install -D posthtml-bootstrap
# Or
yarn add -D posthtml-bootstrap

Usage

import posthtml from 'posthtml'
import posthtmlComponent from 'posthtml-component'
import { defineBootstrapUIConfig } from 'posthtml-bootstrap'

// Use default configuration
const config = defineBootstrapUIConfig()
// Create a PostHTML processor with the plugin
const processor = posthtml([posthtmlComponent(config)])

// Your HTML with Bootstrap components
const htmlString = `
<ui:container>
  <ui:row>
    <ui:col>
      <ui:button variant="primary">Click me!</ui:button>
    </ui:col>
  </ui:row>
</ui:container>
`

processor
  .process(htmlString, {
    recognizeSelfClosing: true
  })
  .then(result => {
    console.log(result.html) // Processed HTML with Bootstrap components
  })

A wide range of Bootstrap components are available for use with this plugin. You can find the complete list of components in the ui directory.

Note: Detailed documentation for each component is currently under development 😉

Configuration Options

To configure Bootstrap UI, use the following JavaScript snippet:

import { defineBootstrapUIConfig } from 'posthtml-bootstrap'

const config = defineBootstrapUIConfig({
  // Options go here
})

Please refer to the posthtml-component documentation to review the available options.

Opinionated options:

The following options are opinionated and cannot be changed:

• root: (string) String value as the root path for component lookup. Always process.cwd().
• tagPrefix: (string) The prefix used for component tags in your HTML. Always ui:.
• yield: (string) The tag name used for the main content area within a component. Always <children />.
• attribute: (string) The attribute used to specify the component path within a tag. Always @src.

Extended Components

posthtml-bootstrap allows you to seamlessly integrate your own custom components alongside the built-in Bootstrap components. This is achieved by referencing the folder path containing your custom components in the folders property of the configuration.

1. Create your custom components:

   Start by creating your custom components as HTML files within a dedicated folder. For example, let's create a components folder and add a simple foo.html component:

   <!-- views/components/foo.html -->
   <div class="foo">This is a custom foo component.</div>

2. Configure the plugin:

   In your JavaScript file, modify the configuration to include the path to your custom components folder:

   import { defineBootstrapUIConfig } from 'posthtml-bootstrap'
   
   const config = defineBootstrapUIConfig({
     folders: ['views/components'] // Add your custom components folder
   })

3. Use your custom components:

   Now you can use your custom component in your HTML just like any other Bootstrap component:

   <ui:container>
     <ui:row>
       <ui:col>
         <ui:foo />
       </ui:col>
     </ui:row>
   </ui:container>

Custom Utilities

The utilities option allows you to provide custom functions that can be accessed within the <script props> block of a component.

const config = defineBootstrapUIConfig({
  utilities: {
    formatPrice(price) {
      return new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: 'USD'
      }).format(+price)
    }
  }
})

Then, use your custom utility function within a component's props script:

<!-- views/components/foo.html -->
<script props>
  const { price } = props

  module.exports = {
    formattedPrice: formatPrice(price)
  }
</script>

<!-- use the formatted price in your component's HTML -->
<p class="foo">The price is: {{formattedPrice}}</p>

Finally, use the ui:foo component like so:

<ui:foo price="1000" />

This will render the formatted price using your custom formatPrice function:

<p class="foo">The price is: $1,000.00</p>

Contributing

We 💛  issues.

When committing, please conform to the semantic-release commit standards. Please install commitizen and the adapter globally, if you have not already.

npm i -g commitizen cz-conventional-changelog

Now you can use git cz or just cz instead of git commit when committing. You can also use git-cz, which is an alias for cz.

git add . && git cz

License

A project by Stilearning © 2024.