diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index b1fab7ec1..795fb3e7e 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -1,63 +1,91 @@ -## Quick and Dirty Set-up +## Getting Semantic UI -1) Rename the site configuration folder from ``/themes/_site`` to ``themes/site`` to avoid library updates modifying your site's settings. +For links to download Semantic UI, check our our [download page](http://www.learnsemantic.com/guide/download.html). -2) Rename your semantic config file from ``semantic.config.example`` to ``semantic.config`` +## Setting Up -3) Use ``grunt build`` to output your project files, you can configure the paths used in ``grunt.config``. +### Dependencies +Semantic uses command-line tools to build your project while theming. After getting Semantic, you will need to install [nodejs](http://nodejs.org/download/) and [gulp](https://github.com/gulpjs/gulp/) to run the build process. -## Overview -* ``definitions/`` - contain all UI definitions -* ``themes/packaged/default`` are the default UI styling of an element -* ``themes/packaged`` are downloaded from the web or a package manager and provide preset overrides -* ``themes/user`` are the only files you should modify, these are your site's overrides for LESS and variables +Once you're up and running. Navigate to the semantic directory and install the npm dependencies +```bash + # install dependencies + npm install + # start install script + gulp +``` -## Building CSS +### Installing Semantic -To make development easier, Semantic has a built in grunt config for building your project. Simply modify the **grunt.config** with the directories you need. +The first time you run gulp you will be greeted with an interactive installer +```bash + # install + gulp +``` -You can also build the source files with any processor for LESS. Just keep in mind to customize ``site.variables`` with your asset paths for images and fonts. +The installer will let you select which components to include, and specify paths for your project. -For information on installing grunt [see their guide](http://gruntjs.com/installing-grunt) +| | Installation Type | +| ------------- | ------------- | +| Automatic | Installation will use the default paths, outputing css files to `dist/` and packaging all components together | +| Express | Will let you move your site folder and your dist folder and select from a list of components to include in your concatenated release. | +| Custom | Will prompt you for all available options | -## Customizing Semantic +The install process will create two files: `semantic.json` stores paths for your build and sits on the top-level of your project, `theme.config` is a **LESS** file that exists in **src/** and allows you to centrally set the themes for each UI component. -**There is only one folder you should ever edit files in ``themes/site``.** These are your site's LESS overrides and variable settings. +The installer will also create a special folder which contains your site-specific themes. The default location for this is `src/site`. For more information on using site themes, see the theming guide below. -### Using a default theme -Leaving an element as ``default`` will use baseline UI stylings. +### Manual Install +If you prefer these files and folders can be moved manually instead of using the installer. +```bash + mv semantic.json.example semantic.json + mv src/theme.config.example src/theme.config + mv src/_site src/site + vi semantic.json +``` -The inheritance order when using default is: -1) ``themes/default/elements/button.variables`` loads the baseline UI variables -2) ``themes/packaged/default/elements/button.variables`` loads a blank file -3) ``themes/sites/elements.button.variables`` loads your variable overrides +### Upgrading Semantic -### Using a packaged theme -Packaged themes can be downloaded from the internet, and placed inside ``themes/packaged/`` +You can use normal package manager functions to update your project, just be sure to re-install semantic after upgrading. Re-install will **extend your `semantic.json` but not overwrite it** +```bash + bower update + cd ./bower_modules/semantic-ui + gulp install +``` -To use a packaged theme change the value inside ``semantic.config`` to the theme name. +> For a full list of settings for **semantic.json**, check the defaults values which it inherits from. -For example if you change your button theme to 'chubby' the following load order would occur: +## Using Semantic Build Tools -1) ``themes/default/elements/button.variables`` loads the UI variables -2) ``themes/packaged/chubby/elements/button.variables`` loads the "downloadable" theme (this will allow for community packages) In this example, a button theme called *chubby* -3) ``themes/sites/elements.button.variables`` loads **your overrides for variables** +### Gulp commands +After setting up your project you have access to several commands for building your css and javascript. -## Adjust your site's configuration +```bash + gulp # runs default task (watch) + gulp watch # watches files for changes + gulp build # builds all files from source + gulp install # re-runs install +``` -To customize a ``ui button`` you can -* Add variable overrides in ``site/elements/button.variables`` -* Add user LESS/CSS overrides in ``/site/elements/button.overrides`` (this will have all variables accessible) -Semantic now also includes some site-wide configuration by default in ``site.less`` it is recommended you include this also. +Semantic creates minified, and uncompressed files in your source for both individual components, and the components specified for your packaged version. -## Advanced grunt usage -``grunt reset`` - Clears your build directory. Use this if you have a source file that is no longer being tracked. +Keep in mind semantic will automatically adjust URLs in CSS and add vendor-prefixes as part of the build process. This means **definitions and theme files do not need vendor prefixes**. -``grunt build`` - This will build all files (not just watched files) in your source directory +#### Advanced Usage -## Gotchas & Tips +> In addition to the paths set in `semantic.json`, you can serve files to a second location, for example, a docs instance by using a separate config file `tasks/admin/docs.json`. Using a copy of the SUI documentation may work well internally for creating a style guide to hack on the theme designs for your project. +```bash + gulp serve-docs + gulp build-docs +``` +### Workflow -Semantic **now requires a box-sizing reset** this allows us more flexibility inside the framework to not deal with issues related to calculating padding. This is included in ``site.less`` as well as a standard HTML reset. +Building and watching Semantic is only necessary while adjusting your UI. This is usually the first part of building a new project, and a separate process than building-out pages in your site. +During this architecting phase you can try downloading different themes, adjusting your site-wide settings (font-family, colors, etc) and tweaking components in your site's component overrides. +Files in the `examples/` folder of your project can be useful for testing out changes in your UI. For example, you might run `gulp watch` download a new theme to `src/site/themes/` then adjust your `theme.config` file with the name of the new theme and refresh `examples/kitchensink.html` to inspect changes in the theme. +You will only need to use Semantic's build tools while refining your UI, while designing pages you can rely on the packages in `dist/` and your software stack's normal build set-up. + + `gulp watch` will automatically recompile only the necessary definition files when you update `semantic.config` or any `.variables` or `.overrides` file.