mdbootstrap/mdb-ui-kit
1
1
Fork 0
mirror of https://github.com/mdbootstrap/mdb-ui-kit.git synced 2025-02-02 21:04:13 +03:00
Code Issues Packages Projects Releases Wiki Activity

documentation updates

Browse Source
This commit is contained in:
Kevin Ross 2015-12-24 10:44:35 -06:00
parent 1a7421fb99
commit 9886b2f7ce
9 changed files with 140 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
CONTRIBUTING.md
View File

@ -208,49 +208,3 @@ check tools and provid feedback.
By contributing your code, you agree to license your contribution under the [MIT License](LICENSE).
By contributing to the documentation, you agree to license your contribution under the [Creative Commons Attribution 3.0 Unported License](docs/LICENSE).
## Development setup
The development and testing with the documentation has been connected so we not only can utilize Material Design examples,
but all of the original Bootstrap documentation examples as well. The most productive environment so far is to have
Bootstrap checked out in parallel to this project, running three different terminal commands simultaneously:
1. Bootstrap documentation
```bash
cd bootstrap
bundle install
npm install
# update docs and serve
grunt dist docs && jekyll serve
```
1. Initial build and watch
This performs an initial build and watches both the core and docs sources for changes.
```bash
cd bootstrap-material-design
bundle install
npm install
# this is all you need after initial setup
grunt dist docs watch
```
1. Documentation
(assuming the above is done)
```bash
jekyll serve
```
## Releasing
1. Make sure travis succeeds first
1. Update the version in `package.json`, it's version is used in the documentation
1. Build the distribution `grunt prep-release`
1. Commit
1. Tag for bower - a valid tag starts with a `v` such as `v4.0.0`
1. Push documentation with `grunt publish`

2
Gruntfile.js
View File

@ -666,7 +666,7 @@ module.exports = function (grunt) {
grunt.registerTask('dist-css', ['sass-compile', 'postcss:core', 'csscomb:dist', 'cssmin:core', 'cssmin:docs']);
// Full distribution task.
grunt.registerTask('dist', ['clean:dist', 'dist-css', 'dist-js']);
grunt.registerTask('dist', ['clean:dist', 'dist-css', 'dist-js', 'docs']);
// Default task.
grunt.registerTask('default', ['clean:dist', 'test']);

6
docs/_data/nav.yml
View File

@ -3,10 +3,10 @@
- title: Introduction
- title: Download
- title: Browsers & devices
- title: Options
- title: Flexbox
- title: Build tools
- title: Customization
- title: Best practices
- title: Build tools
- title: Release process
- title: Material Design
pages:

7
docs/getting-started/browsers-devices.md
View File

@ -4,6 +4,13 @@ title: Browsers and devices
group: getting-started
---
{% callout info %}
**Bootstrap Reference Documentation**
This is a part of the reference documentation from <a href="http://getbootstrap.com">Bootstrap</a>.
It is included here to ensure this critical information about compatibility is conveyed.
{% endcallout %}
Bootstrap supports a wide variety of modern browsers and devices, and some older ones. See which exact ones below, as well as detailed information on known quirks and bugs.
## Contents

36
docs/getting-started/build-tools.md
View File

@ -52,7 +52,8 @@ Material Design for Bootstrap uses [Autoprefixer][autoprefixer] (included in our
## Local documentation
Running our documentation locally requires the use of Jekyll, a decently flexible static site generator that provides us basic includes, Markdown-based files, templates, and more. Here's how to get it started:
Running our documentation locally requires the use of Jekyll, a flexible static site generator that provides us basic includes,
markdown-based files, templates, and more. Here's how to get it started:
1. Run through the [tooling setup](#tooling-setup) above to install Jekyll (the site builder) and other Ruby dependencies with `bundle install`.
2. From the root `/bootstrap-material-design` directory, run `bundle exec jekyll serve` in the command line.
@ -60,6 +61,39 @@ Running our documentation locally requires the use of Jekyll, a decently flexibl
Learn more about using Jekyll by reading its [documentation](http://jekyllrb.com/docs/home/).
## Local development setup
The development and testing with the documentation has been connected so we not only can utilize Material Design examples,
but all of the original Bootstrap documentation examples as well. The most productive environment so far is to have
Bootstrap checked out in parallel to this project, running three (3) different terminal commands simultaneously:
1. _Terminal 1_: Bootstrap documentation for reference
1. Performs an initial dependency setup/build
`bundle install && npm install && bower install && grunt dist`
1. Start serving the documentation on <http://localhost:9000>
`jekyll serve`
1. _Terminal 2_: Initial build and watch
1. Performs an initial dependency setup/build
`bundle install && npm install && bower install && grunt dist`
1. Watch both the core and docs sources for changes
`grunt watch`
1. _Terminal 3_: Start serving documentation on <http://localhost:9001> with `jekyll serve`
Now go forth and develop, the `watch` task will keep tabs on source files and docs files, meanwhile the `jekyll serve` command
will generate new documentation pages with the changes. Simply refresh your browser to see the changes.
(TODO: someone please investigate adding autoreload to jekyll development cycle)
## Troubleshooting
Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`.

44
docs/getting-started/customization.md Normal file
View File

@ -0,0 +1,44 @@
---
layout: docs
title: Customization options
group: getting-started
---
Material Design for Bootstrap 4 is designed to be customized via Sass variables. You may customize any Bootstrap or MDB variable.
{% callout info %}
The following assumes you have [setup your Build tools](../build-tools)
{% endcallout %}
{% callout warning %}
If overriding a variable via Sass, ensure that your are `@import`ing the _underscored_ file `_core.scss` **not** the main file used for distributions. For more information see this [StackOverflow post](http://stackoverflow.com/a/25191403/2363935).
{% endcallout %}
Here are some ways to customize:
## 1. (Recommended) Include the source in your application
Installing via Bower, customizing MDB is a breeze.
1. Add `bootstrap-material-design` as a dependeny to your `bower.json`
1. `bower install`
1. In your application's Sass, redefine any customized variable _before_ `@import`ing bootstrap material design from your bower dependency directory. For example:
~~~~~~~~
$brand-primary: #3f51b5; // bootstrap variable
$mdb-label-color-focus: #303f9f; // mdb variable
@import "../bower_components/bootstrap-material-design/scss/core"; // make sure to use _core.scss!
~~~~~~~~
## 2. Download the source and change/compile
{% callout warning %}
This method is not recommended because it may be difficult to use source control **and** keep up to date with new releases. Please consider the recommended method above.
{% endcallout %}
1. Download the source via bower or otherwise
2. Change any of the variables
3. Run `grunt dist`

51
docs/getting-started/flexbox.md
View File

@ -1,51 +0,0 @@
---
layout: docs
title: Flexbox
group: getting-started
---
Flexbox support has finally come to Bootstrap. Opt-in to the new CSS layout styles with the flick of a variable or the swap of a stylesheet.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## What's included
Flexbox support is available for a number of Bootstrap's components:
- The entire grid system (mixins and predefined classes), which switch from `float`s to `display: flex;`.
- Input groups, which move from `display: table;` to `display: flex;`.
- The media component moves from `display: table;` and a number of hacky styles to a simple `display: flex;`.
Vendor prefixes are provided in our compiled CSS with Autoprefixer via Grunt.
## Why flexbox?
In a nutshell, flexbox provides simpler and more flexible layout options in CSS. More specifically, it provides:
- Easy vertical alignment of content within a parent element.
- Easy reordering of content across devices and screen resolutions with the help of media queries.
- Easy CSS-only equal height columns for your grid-based layouts.
All these things are possible outside flexbox, but typically require extra hacks and workarounds to do right.
## How it works
If you're familiar with modifying variables in Sass—or any other CSS preprocessor—you'll be right at home to move into flexbox mode.
1. Open the `_variables.scss` file and find the `$enable-flex` variable.
2. Change it from `false` to `true`.
3. Recompile, and done!
Alternatively, if you don't need the source Sass files, you may swap the default Bootstrap compiled CSS with the compiled flexbox variation. [Head to the download page]({{ site.baseurl }}/getting-started/download) for more information.
## Browser support
Enabling flexbox means **reduced browser and device support:**
- Internet Explorer 9 and below do not support flexbox.
- Internet Explorer 10 has a few known quirks (see the "Known issues" tab in [Can I use...](http://caniuse.com/#feat=flexbox)), requires using a prefix, and only supports the syntax from the old 2012 version of the spec.
Please be extra conscious of your user base when enabling flexbox in your project. Visit [Can I use...](http://caniuse.com/#feat=flexbox) for details on browser support of flexbox.

101
docs/getting-started/options.md
View File

@ -1,101 +0,0 @@
---
layout: docs
title: Customization options
group: getting-started
---
With Bootstrap 4, we've added a handful of global options for easily customizing all the components in your project. These options are handled by Sass variables. Simply change a variable's value and recompile with the included Gruntfile.
## Available variables
You can find and customize these variables in our `_variables.scss` file.
| Variable | Values | Description |
| --------------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
| `$spacer` | `1rem` (default), or any value > 0 | Specifies the default spacer value for our spacer utilities. |
| `$enable-flex` | `true` or `false` (default) | Swaps `float` and `display: table` styles for `display: flex`. |
| `$enable-rounded` | `true` (default) or `false` | Enables predefined `border-radius` styles on various components. |
| `$enable-shadows` | `true` or `false` (default) | Enables predefined `box-shadow` styles on various components. |
| `$enable-gradients` | `true` or `false` (default) | Enables predefined gradients via `background-image` various components. |
| `$enable-transitions` | `true` (default) or `false` | Enables predefined `transition`s on various components. |
| `$enable-hover-media-query` | `true` or `false` (default) | ... |
## Color palette
Bootstrap's color palette includes a numerical range of shades for each base color, heavily inspired by [Google's color palette](https://www.google.com/design/spec/style/color.html#color-color-palette). Base colors, which utilize Sass color functions to generate each shade, are indicated at the top of each stacked palette.
<div class="row">
<div class="col-sm-6 col-md-4 color-palette">
<div class="color-slab color-slab-base gray-100">100</div>
<div class="color-slab gray-100">100</div>
<div class="color-slab gray-200">200</div>
<div class="color-slab gray-300">300</div>
<div class="color-slab gray-400">400</div>
<div class="color-slab gray-500">500</div>
<div class="color-slab gray-600">600</div>
<div class="color-slab gray-700">700</div>
<div class="color-slab gray-800">800</div>
<div class="color-slab gray-900">900</div>
</div>
<div class="col-sm-6 col-md-4 color-palette">
<div class="color-slab color-slab-base blue-500">500</div>
<div class="color-slab blue-100">100</div>
<div class="color-slab blue-200">200</div>
<div class="color-slab blue-300">300</div>
<div class="color-slab blue-400">400</div>
<div class="color-slab blue-500">500</div>
<div class="color-slab blue-600">600</div>
<div class="color-slab blue-700">700</div>
<div class="color-slab blue-800">800</div>
<div class="color-slab blue-900">900</div>
</div>
<div class="col-sm-6 col-md-4 color-palette">
<div class="color-slab color-slab-base green-500">500</div>
<div class="color-slab green-100">100</div>
<div class="color-slab green-200">200</div>
<div class="color-slab green-300">300</div>
<div class="color-slab green-400">400</div>
<div class="color-slab green-500">500</div>
<div class="color-slab green-600">600</div>
<div class="color-slab green-700">700</div>
<div class="color-slab green-800">800</div>
<div class="color-slab green-900">900</div>
</div>
<div class="col-sm-6 col-md-4 color-palette">
<div class="color-slab color-slab-base teal-500">500</div>
<div class="color-slab teal-100">100</div>
<div class="color-slab teal-200">200</div>
<div class="color-slab teal-300">300</div>
<div class="color-slab teal-400">400</div>
<div class="color-slab teal-500">500</div>
<div class="color-slab teal-600">600</div>
<div class="color-slab teal-700">700</div>
<div class="color-slab teal-800">800</div>
<div class="color-slab teal-900">900</div>
</div>
<div class="col-sm-6 col-md-4 color-palette">
<div class="color-slab color-slab-base orange-500">500</div>
<div class="color-slab orange-100">100</div>
<div class="color-slab orange-200">200</div>
<div class="color-slab orange-300">300</div>
<div class="color-slab orange-400">400</div>
<div class="color-slab orange-500">500</div>
<div class="color-slab orange-600">600</div>
<div class="color-slab orange-700">700</div>
<div class="color-slab orange-800">800</div>
<div class="color-slab orange-900">900</div>
</div>
<div class="col-sm-6 col-md-4 color-palette">
<div class="color-slab color-slab-base red-500">500</div>
<div class="color-slab red-100">100</div>
<div class="color-slab red-200">200</div>
<div class="color-slab red-300">300</div>
<div class="color-slab red-400">400</div>
<div class="color-slab red-500">500</div>
<div class="color-slab red-600">600</div>
<div class="color-slab red-700">700</div>
<div class="color-slab red-800">800</div>
<div class="color-slab red-900">900</div>
</div>
</div>

50
docs/getting-started/release-process.md Normal file
View File

@ -0,0 +1,50 @@
---
layout: docs
title: Release process
group: getting-started
---
Material Design for Bootstrap has a well defined release process that is automated by [Grunt](http://gruntjs.com). See the [Build Tools](../build-tools) section for setup.
## Creating a release
### Add a release issue to Github
Use the following task template:
~~~~~~~~
- [] update `package.json` version
- [] `grunt prep-release`
- [] commit
- [] travis success
- [] tag for bower e.g. `v4.0.0`
- [] push to npm
- [] push to meteor
- [] `grunt publish`
- [] close any milestone
- [] create release and reference milestone issues</code>
~~~~~~~~
### Build the release
1. Update the version in `package.json`, it's version is used in the documentation
1. Build the distribution `grunt prep-release`
1. Commit
1. Ensure travis succeeds
### Bower
Tag for bower - a valid tag starts with a `v` such as `v4.0.0`
### NPM
TODO: push to npm?
### Meteor
TODO: push to meteor?
### Github tasks
1. Push documentation with `grunt publish`
1. Close any related open milestone
1. Create a release and reference the milestone