Skip to content

Expansion of "Customizing Bootstrap", extending using compiled CSS strategy. #10509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 7 commits into from
Closed

Expansion of "Customizing Bootstrap", extending using compiled CSS strategy. #10509

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e868d1d
First part overhaul of 'Customizing Bootstrap' replacing the brief (a…
StevenBlack Sep 7, 2013
bd0deb5
Getting started docs - Customizing Bootstrap
StevenBlack Sep 7, 2013
36ef3ab
Trivial: 'Customizing Bootstrap' section was missing a standard comme…
StevenBlack Sep 7, 2013
810b1a4
See also 'Customizing Bootstrap' appended to the first reference to c…
StevenBlack Sep 7, 2013
a08d818
Implemented several changes suggested by @mdo
StevenBlack Sep 9, 2013
aab30e7
Swiched most instances of 'compiled' to 'precompiled' for consistency…
StevenBlack Sep 9, 2013
b539230
Getting-started: Miscellaneous code tidy, and now passing all Travis …
StevenBlack Sep 20, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 44 additions & 31 deletions getting-started.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ <h3 id="download-cdn">Bootstrap CDN</h3>

<div class="bs-callout bs-callout-warning" id="callout-less-compilation">
<h4>Compiling Bootstrap's LESS files</h4>
<p>If you work with Bootstrap's uncompiled source code, you need to compile the LESS files to produce usable CSS files. For compiling LESS files into CSS, we only officially support <a href="http://twitter.github.io/recess/">Recess</a>, which is Twitter's CSS hinter based on <a href="http://lesscss.org">less.js</a>.</p>
<p>If you work with Bootstrap's uncompiled source code, you need to compile the LESS files to produce usable CSS files. For compiling LESS files into CSS, we only officially support <a href="http://twitter.github.io/recess/">Recess</a>, which is Twitter's CSS hinter based on <a href="http://lesscss.org">less.js</a>. See also <a href="#customizing">Customizing Bootstrap</a>.</p>
</div>
</div>

Expand Down Expand Up @@ -888,33 +888,37 @@ <h4>It does not require you to:</h4>
<p>The full Bootstrap license is located <a href="{{ site.repo }}/blob/master/README.md">in the project repository</a> for more information.</p>
</div><!-- /.bs-docs-section -->


<!-- Customizing Bootstrap
================================================== -->
<div class="bs-docs-section">
<div class="page-header">
<h1 id="customizing">Customizing Bootstrap</h1>
</div>
<p class="lead">Bootstrap is best maintained when you treat it as a separate and independently-versioned dependency in your development environment. Doing this makes upgrading Bootstrap easier in the future.</p>

<p>Once you've downloaded and included Bootstrap's styles and scripts, you can customize its components. Just create a new stylesheet (LESS, if you like, or just plain CSS) to house your customizations.</p>

<div class="bs-callout bs-callout-info">
<h4>Compiled or minified?</h4>
<p>Unless you plan on reading the CSS, go with minified stylesheets. It's the same code, just compacted. Minified styles use less bandwidth, which is good, especially in production environments.</p>
</div>

<p>From there, include whatever Bootstrap components and HTML content you need to create templates for your site's pages.</p>

<h3>Customizing components</h3>
<p>You can customize components to varying degrees, but most fall into two camps: <em>light customizations</em> and <em>overhauls</em>. Plenty examples of both are available from third parties.</p>
<p>We define <em>light customizations</em> as superficial changes, for example, color and font changes to existing Bootstrap components. A light customization example is the <a href="http://translate.twitter.com">Twitter Translation Center</a> (coded by <a href="https://twitter.com/mdo">@mdo</a>). Let's look at how to implement the custom button we wrote for this site, <code>.btn-ttc</code>.</p>
<p>The stock Bootstrap buttons require just one class, <code>.btn</code>, to start. Here we extend the <code>.btn</code> style with a new modifier class, <code>.btn-ttc</code>, that we will create. This gives us a distinct custom look with minimal effort.</p>
<p>Our customized button will be coded like this:</p>
<p class="lead">Bootstrap is best maintained as a separately versioned package in your development environment. This makes updating and upgrading Bootstrap easier in the future. To customize Bootstrap, create a new stylesheet, using LESS or just plain CSS, to house your customizations.</p>

<p>Bootstrap's developers use the following steps to author and assemble CSS. This knowledge may help you pick a customization strategy that's right for you.</p>
<p><strong>First the CSS source code is authored and maintained in LESS files</strong> named for their functionality. For example, in files named <code>grid.less</code>, <code>forms.less</code>, and many others. If you are comfortable using build tools, then consider using LESS to customize Bootstrap.</p>
Copy link
Member

@mdo mdo Sep 9, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"First, the..."

The second sentence here sounds incomplete. Perhaps use "For example, in grid.less you'll find the code for generating our grid system's CSS."

Copy link
Contributor Author

@StevenBlack StevenBlack Sep 9, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch.

<p><strong>Next individual LESS files are <em>compiled</em> into an unminified CSS file named <code>bootstrap.css</code></strong>. See the source in <code>bootstrap.less</code> to understand how it all comes together. If you require only modest customizations, then extending Bootstrap's <em>compiled</em> CSS directly with your own CSS stylesheet will work for you.</p>
Copy link
Member

@mdo mdo Sep 9, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Next, individual..."

Why the emphasis around the two instances of "compiled" here?

Copy link
Contributor Author

@StevenBlack StevenBlack Sep 9, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Emphasis here because I'm having issues with using "compiled" as well. I'll work on that.

<p><strong>Finally the <code>bootstrap.css</code> file is compressed into and saved to <code>bootstrap.min.css</code></strong>. This CSS is difficult to read, so we recommend using this minified CSS only for deployment, not development.</p>
Copy link
Member

@mdo mdo Sep 9, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Finally, the..."

Perhaps compressed and saved as <code>bootstrap.min.css</code>?

I'd flip the emphasis around the readability, as it's quite intentional and useful. Maybe something like "By compressing, we remove all white space and comments for a smaller file size, perfect for production deployment."

Copy link
Contributor Author

@StevenBlack StevenBlack Sep 9, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. Done!

<p>So you have two choices: you can customize based on the compiled CSS, or if you're happy using build tools, you can customize earlier at the LESS stage.
Copy link
Member

@mdo mdo Sep 9, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"In short, you have two choices: customize on top of the precompiled CSS or use build tools to customize at the source with LESS."

@cvrebert has pushed for the precompiled term instead of compiled. I think that might help here for clarity and brevity.


<h2>Customizing from compiled CSS</h2>
<p>You can customize Bootstrap and its components to varying degrees, but most fall into two categories: <em>light customizations</em> and <em>overhauls</em>. We define <em>light customizations</em> as superficial changes, for example, color and font changes to existing Bootstrap components.</p>
<p>Most light customizations can be made by extending Bootstrap's compiled CSS with an additional and separate style sheet of your own.
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">Example: extending Bootstrap's compiled CSS to customize a component</h3>
</div>
<div class="panel-body">
<p>This example comes from the <a href="http://translate.twitter.com">Twitter Translation Center</a> (coded by <a href="https://twitter.com/mdo">@mdo</a>). Let's look at how to implement the custom button we wrote for this site, <code>.btn-ttc</code>.</p>
<p>The stock Bootstrap buttons require just one class, <code>.btn</code>, to start. Here we extend the <code>.btn</code> style with a new modifier class, <code>.btn-ttc</code>, that we will create. This gives us a distinct custom look with minimal effort.</p>
<p>Our customized button will be coded like this:</p>
{% highlight html %}
<button type="button" class="btn btn-ttc">Save changes</button>
<button type="button" class="btn btn-ttc">Save changes</button>
{% endhighlight %}
<p>Note how <code>.btn-ttc</code> is added to the standard <code>.btn</code> class.</p>
<p>Note how <code>.btn-ttc</code> is added to the standard <code>.btn</code> class.</p>

<p>To implement this, in the custom stylesheet, add the following CSS:</p>
<p>To implement this, in the custom stylesheet, add the following CSS:</p>

{% highlight css %}
/* Custom button
Expand Down Expand Up @@ -945,23 +949,32 @@ <h3>Customizing components</h3>
}
{% endhighlight %}

<p>In short: Look to the style source and duplicate the selectors you need for your modifications.</p>
<p><strong>In summary, here's the basic workflow:</strong></p>
<p><strong>The takeaway from this example</strong> is look to the style source and duplicate the selectors you need for your modifications.</p>

</div>
</div>


<p><strong>In summary, here's the basic workflow for customizing Bootstrap from its compiled CSS:</strong></p>
<ul>
<li>For each element you want to customize, find its code in the compiled Bootstrap CSS.</li>
<li>Copy the component's selector and styles and paste them in your custom stylesheet. For instance, to customize the navbar background, just copy the <code>.navbar</code> style specificaton.</li>
<li>In your custom stylesheet, edit the CSS you just copied from the Bootstrap source. No need for prepending additional classes, or appending <code>!important</code> here. Keep it simple.</li>
<li>Rinse and repeat until you're happy with your customizations.</li>
</ul>
<p>Once you are comfortable performing light customizations, visual overhauls are just as straightforward. For a site like <a href="http://yourkarma.com">Karma</a>, which uses Bootstrap as a CSS reset with heavy modifications, more extensive work is involved. But the same principle applies: include Bootstrap's default stylesheet first, then apply your custom stylesheet.</p>

<div class="bs-callout bs-callout-info">
<h4>Alternate customization methods</h4>
<p>While not recommended for folks new to Bootstrap, you may use one of two alternate methods for customization. The first is modifying the source <code>.less</code> files (making upgrades super difficult), and the second is mapping source LESS code to <a href="http://ruby.bvision.com/blog/please-stop-embedding-bootstrap-classes-in-your-html">your own classes via mixins</a>. For the time being, neither of those options are documented here.</p>
<div class="panel panel-danger">
<div class="panel-heading">
<h3 class="panel-title">Controlling bloat</h3>
</div>
<div class="panel-body">
<p>Not all sites and applications need to make use of everything Bootstrap has to offer, especially in production environments where optimizing bandwidth is an issue. We encourage you to remove whatever is unused with our <a href="../customize/">Customizer</a>.</p>
<p>Using the <a href="/customize">Customizer</a>, simply uncheck any component, feature, or asset you don't need. Hit download and swap out the default Bootstrap files with these newly customized ones. You'll get vanilla Bootstrap, but without the features *you* deem unnecessary. All custom builds include compiled and minified versions, so use whichever works for you.</p>
</div>
</div>
</div>

<h3>Removing potential bloat</h3>
<p>Not all sites and applications need to make use of everything Bootstrap has to offer, especially in production environments where optimizing bandwidth is an issue. We encourage you to remove whatever is unused with our <a href="../customize/">Customizer</a>.</p>
<p>Using the Customizer, simply uncheck any component, feature, or asset you don't need. Hit download and swap out the default Bootstrap files with these newly customized ones. You'll get vanilla Bootstrap, but without the features *you* deem unnecessary. All custom builds include compiled and minified versions, so use whichever works for you.</p>

<h2>Overhauls</h2>
<p>Once you are comfortable performing light customizations, visual overhauls are usually just as straightforward. For a site like <a href="http://yourkarma.com">Karma</a>, which uses Bootstrap as a CSS reset with heavy modifications, more extensive work is involved.</p>
<p>But the same principle applies: include Bootstrap's default stylesheet first, then apply your custom stylesheet.</p>
</div>