Transforms a generic XML document into Bootstrap HTML pages
1.6K
Transforms a generic XML document into Bootstrap HTML pages.
XML-to-Bootstrap is a set of tools to generate static web pages. Input is defined in the form of an Extensible Markup Language (XML) document. The output is a web page comprising HTML, CSS and JavaScript files. The transformation is performed by using Extensible Stylesheet Language Transformations (XSLT), as well as several JavaScript utilities invoked as Grunt tasks.
Take a look at the Demo site to learn how generated pages look like.
XML-to-Bootstrap is a static site generator, similar to popular Jekyll, Middleman, or Hugo. But as opposed to these projects, which provide flexible general purpose tools, XML-to-Bootstrap (currently) focuses on a single, very specific use case. It only generates a certain type of web page. If you're looking for something more customizable then I'd strongly suggest to check out Jekyll or the like.
XML-to-Bootstrap requires an XSLT processor such as xsltproc, GraphicsMagick, as well as Node.js:
On RedHat-like Linux:
# sudo dnf install libxslt GraphicsMagick npm
On Debian-like Linux:
# sudo apt-get install xsltproc graphicsmagick npm
# sudo ln -s /usr/bin/nodejs /usr/bin/node
On Arch-like Linux:
# sudo pacman -S libxslt graphicsmagick npm
Several options are available for getting the code:
git clone https://github.com/acch/XML-to-bootstrap.gitOnce code is downloaded, cd into the directory and install necessary prerequisites (including Grunt):
# npm install
# sudo npm install -g grunt-cli
Bootstrap is integrated as a Git submodule. Fetch and build it with the following command:
# grunt init
With all prerequisites installed, build the project:
# grunt
If all goes well you end up with a set of static web pages in the publish/ directory. Transfer them to your web server and enjoy!
Grunt provides a minimal web server, which can be used to preview the results. To do so, run the following command and point your browser to http://localhost:8000:
# grunt connect
To get started with your own content simply modify the source files in the src/ directory and rebuild using grunt. Don't worry, your modifications will not be overwritten by future updates of XML-to-Bootstrap.
The installation can also be performed automatically by building a Docker image and running a container from it. You can simply use the pre-built image acch/xml-to-bootstrap, unless you want to customize the Bootstrap theme. For custom Boootstrap builds you will need to build your own Docker image as explained below.
Use the following commands to build a Docker image. This will download the necessary code, compile Bootstrap, and install all prerequisites necessary to build the project. Be patient, this may take a while.
# git clone https://github.com/acch/XML-to-bootstrap.git
# cd XML-to-bootstrap && docker build -t x2b .
The following command will run a container from the image, in turn building your project:
# docker run --rm -v $(pwd)/src:/build/src -v $(pwd)/publish:/build/publish x2b
Any further arguments will be passed to Grunt directly. Thus, in order to build a debug version of your project simply run:
# docker run --rm -v $(pwd)/src:/build/src -v $(pwd)/publish:/build/publish x2b debug
Grunt provides a minimal web server, which can be used to preview the results. To do so, run the following command and point your browser to http://localhost:8000:
# docker run -d -v $(pwd)/publish:/build/publish -p 8000:8000 x2b connect
After you've successfully built and run the demo pages you can get started with your own content. To do so, modify the source files in the src/ directory according to your needs. Your static web pages are available in the publish/ directory after you've run a container to build them.
Note that once you've customized the Bootstrap theme (by editing sass/customvars.scss) you'll need to (re-)build the image using:
# docker build -t x2b .
The project comprises files in the following directories:
XML-to-bootstrap/ Contains build instructions and documentation
├── css/ Contains 3rd party CSS stylesheets used during build
├── img/ Contains image resources used during build
├── js/ Contains JavaScript code used during build
├── lib/ Contains 3rd party libraries fetched with Bower and used during build
├── modules/ Contains Git submodules such as Bootstrap
├── publish/ Contains the generated static web pages
├── sass/ Contains SCSS templates which are compiled into CSS stylesheets
│ └── sample/ Contains sample SCSS to act as template for overriding Bootstrap variables
├── src/ Contains the XML document describing your web pages
│ ├── img/ Contains image resources for your web pages
│ ├── sample/ Contains sample XML to act as template for new web pages
│ └── sampleimg/ Contains sample image resources for demo web pages
└── style/ Contains XSL stylesheets used to generate static web pages from the XML document
css, img and lib are temporary directories which can be deleted. They will be recreated during build.
The Grunt task runner is used to build static web pages. The following Grunt tasks are available:
| Task | Description |
|---|---|
| init | Initializes Bootstrap submodule and builds custom theme |
| clean | Deletes previously generated output and temporary files |
| default | Generates minified output with development URLs — use this for development |
| debug | Skips minification and instead generates readable output — use this for development |
| prod | Generates minified output with production URLs — use this for production |
| connect | Start minimal web server on port 8000 used for development |
To get started with your own site simply modify the source files in the src/ directory. When populating the XML document with your own content, remember to use character entity numbers instead of names. Character entity names are not defined in XML. For example, will not work — you will need to use   instead. Refer to the HTML5 Character Reference for a complete list with mappings.
Here are some popular characters to use:
| Entity Name | Entity Number | Description | |
|---|---|---|---|
| |   | Non-breaking space | |
| — | — | — | Em dash |
| … | … | … | Ellipsis |
Generated static web pages end up in the publish/ directory. During development you will most likely want to invoke grunt connect for running a local web server at http://localhost:8000. When publishing the final web pages then the URLs used inside HTML documents need to be adjusted in order to reflect the address of the production web server. Use the grunt prod target for generating web pages with production URLs. These URLs are defined with the following options:
# options.xml
<option name="site.url" devmode="dev">//localhost:8000/</option>
<option name="site.url" devmode="prod">//acch.github.io/XML-to-bootstrap/</option>
<option name="site.assets.url" devmode="dev">//localhost:8000/assets/</option>
<option name="site.assets.url" devmode="prod">//acch.github.io/XML-to-bootstrap/assets/</option>
XML-to-bootstrap can automatically generate a navigation sidebar for your pages. This happens if you equip your elements (typically headings) with an id attribute. Thus, if you use <h2>–<h6> tags with a unique id attribute to group your content into sections then a sidebar will be generated with links to these anchors. If you skip the id attribute then no sidebar will show up.
Image resources are stored in subdirectories underneath src/img/. You need to create a separate subdirectory for each article and for each project using images. The naming convention is src/img/[article|project]/<id>/somepic.jpg. Note that the directory name must match the id of the article / project (as defined by the id attribute). If no id attribute is defined then the path will be generated from the title — same as the article / project's filename (without extension).
Here's an example:
src/
└── img/
├── article/
│ ├── first-article/
│ │ └ somepic.jpg
│ ├── another-article/
│ │ └ somepic.png
│ └── yet-another-article/
│ ├ somepic.gif
│ └ anotherpic.jpg
└── project/
├── project-one/
│ └ goodpic.jpg
├── project-two/
│ └ betterpic.jpg
└── project-three/
└ bestpic.jpg
When generating the HTML document, XML-to-Bootstrap will automatically prepend the article / project's path to the image's src attribute. This means that in the XML document you can simply use the following syntax to insert images:
# articles.xml
<article id="first-article">
...
<img src="somepic.jpg" />
...
</article>
Or alternatively, if no id attribute is defined:
# articles.xml
<article>
...
<title>First Article!</title>
...
<img src="somepic.jpg" />
...
</article>
The file sass/customvars.scss can be used to override Bootstrap variables, resulting in a custom Bootstrap theme. Add any Sass variables you wish to override to this file. Note that Bootstrap needs to be rebuilt after making changes to customvars.scss — use the grunt init task for that purpose.
For more information on Bootstrap's customization options refer to the documentation or simply read the definitions and comments in modules/bootstrap/scss/_variables.scss.
As the Bootstrap theme is included in the Docker image you will not be able to use the pre-built image acch/xml-to-bootstrap, but instead need to build your own image. Furthermore, the Docker image needs to be rebuilt every time after making changes to customvars.scss. Use the following command for that purpose:
docker build -t x2b .
If Grunt complains about JavaScript syntax errors during build then update to the latest version of Node.js via npm install -g n && n stable. Alternatively, use the NodeSource repository to install the latest Node.js version for your platform.
You have a question, found a bug, or have an idea how to make this tool better? Great — your feedback is highly appreciated! Please use the issue tracker to get in touch.
Please consider making your modifications and extensions available to others. Refer to the CONTRIBUTING document for details.
Copyright Achim Christ, released under the MIT license.
Content type
Image
Digest
Size
704.3 MB
Last updated
about 9 years ago
docker pull acch/xml-to-bootstrap