posthtml-bootstrap
TypeScript icon, indicating that this package has built-in type declarations

1.0.4 • Public • Published

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

GitHub

A project by Stilearning © 2024.

Package Sidebar

Install

npm i posthtml-bootstrap

Weekly Downloads

6

Version

1.0.4

License

MIT

Unpacked Size

58.7 kB

Total Files

94

Last publish

Collaborators

  • bent10