<p>Component repos are released on NPM and as tagged releases on github.</p>
<p>Check the list of repos available under <a href="https://github.com/Semantic-Org?utf8=%E2%9C%93&query=ui-">Semantic Org</a> on GitHub</p>
<p>Each component's release notes will automatically update with the relevant notes for that component from the main release.</p>
@ -37,9 +37,10 @@ type : 'Introduction'
npm install semantic-ui-component
</div>
</div>
<div class="no example">
<h4>Server-Side Rendering</h4>
<p>Individual components repos include an <code>index.js</code> file to simplify <a href="http://www.sitepoint.com/understanding-module-exports-exports-node-js/" target="_blank"><code>require</code></a> use with NodeJS, for server-side rendering or with <a href="http://browserify.org/" target="_blank">Browserify</a>.</p>
<p>Individual components repos include an <a href="https://github.com/Semantic-Org/Semantic-UI/blob/master/tasks/admin/components/create.js" target="_blank">auto-generated</a> <code>index.js</code> file to simplify <a href="http://www.sitepoint.com/understanding-module-exports-exports-node-js/" target="_blank"><code>require</code></a> use with NodeJS, for server-side rendering or with <a href="http://browserify.org/" target="_blank">Browserify</a>.</p>
<p>A special distribution <a href="https://github.com/Semantic-Org/Semantic-UI-LESS">Semantic-UI-LESS</a> is available for projects that use custom integrations and do not require our build tools.</p>
<h4>All Components</h4>
<div class="ui ignored warning message">LESS source files are not prefixed, and will need to be run through <a href="https://github.com/postcss/autoprefixer">autoprefixer</a> before being used</div>
</div>
<div class="no example">
<h4>Importing Semantic</h4>
<p><code>semantic.less</code> is available in all releases as an entry point for importing multiple components from other LESS files.</p>
<p>Before LESS files will work correctly you will to manually rename <code>theme.config.example</code>.
<p>To begin using a site theme you will also need to rename <code>_site/</code> to <code>site/</code>.</p>
<div class="ui ignored warning message">LESS source files are not prefixed, and will need to be run through <a href="https://github.com/postcss/autoprefixer">autoprefixer</a> before being used</div>
</div>
<div class="no example">
<h4>Single Components</h4>
<h4>Importing Components</h4>
<p>If you need to import individual components, you should scope each import to avoid inheritance issues.</p>
<div class="ignored code" data-type="LESS" data-title="Importing LESS Components">
<p>Semantic UI's documentation is written in <a href="http://www.docpad.org" target="_blank">Docpad</a> an amazing static site generator built in NodeJS</p>
<div class="code">
cd docs/
npm install
</div>
</div>
<div class="no example">
<h4>A Note About Paths</h4>
<p>Semantic UI's <a href="introduction/build-tools.html">build tools</a> include two special commands <code>build-docs</code> and <code>serve-docs</code> for use with the documentation. These will pass changes from the ui/ folder directly to a live docs server.</p>
<p>These gulp tasks expect two sibling folders</p>
<div class="ui list">
<div class="item">
<i class="folder icon"></i>
<div class="content">
<div class="header">ui/</div>
<div class="description">Files from semantic ui repo</div>
</div>
</div>
<div class="item">
<i class="folder icon"></i>
<div class="content">
<div class="header">docs/</div>
<div class="description">Files from docs repo</div>
</div>
</div>
</div>
</div>
<div class="no example">
<h4>Build UI</h4>
<p>The first time you run docs you will need to build the whole project once</p>
<div class="code">
cd ui/
gulp build-docs
</div>
</div>
<div class="no example">
<h4>Run Docpad Server</h4>
<p>Docpad</p>
<div class="code">
cd docs/
# initial build may take several minutes
docpad run
</div>
</div>
<div class="no example">
<h4>Serve UI to Docs</h4>
<p>You can then continue to make modifications to UI and "serve" these files to a live docs instance to see your changes immediately</p>
<div class="code">
cd ui/
gulp build-docs
</div>
</div>
<div class="no example">
<h4>Hosted Docs</h4>
<p>If you are managing your documentation you can automatically deploy to github pages using a built in <a href="https://github.com/docpad/docpad-plugin-ghpages">docpad gh-pages</a> plugin</p>
<p>For more information about GitHub pages, check out the <a href="https://pages.github.com/" target="_blank">docs on GitHub</a></p>
<div class="code">
docpad deploy-ghpages --env static
</div>
</div>
<div class="no example">
<h4>Custom Docs Paths</h4>
<p>Doc task paths are specified in a file <a href="https://github.com/Semantic-Org/Semantic-UI/blob/master/tasks/config/docs.js"><code>tasks/config/docs.js</code></a> and can be adjusted to use any folder set-up necessary for your project.</p>
<p><a href="/introduction/getting-started.html">Download Semantic UI</a> navigate to the install folder then run a <a href="#gulp-commands">gulp command</a>.</p>
<p>To build all files:</p>
<div class="code" data-type="bash">
gulp build
</div>
<p>To watch for changes</p>
<div class="code" data-type="bash">
gulp watch
</div>
</div>
<div class="no example">
<h4>Why Build Tools?</h4>
<p>Semantic UI uses Gulp for several reasons:</p>
@ -102,7 +116,7 @@ type : 'Introduction'
</div>
</div>
<div class="no example">
<h4>Available Commands</h4>
<h4>Gulp Commands</h4>
<p>Below is a list of all available gulp commands</p>
<table class="ui definition table">
<thead>
@ -112,7 +126,7 @@ type : 'Introduction'
<tbody>
<tr>
<td>install</td>
<td>Asks install questions will automatically run if not setup.</td>
<td>Asks install questions to setup semantic.json</td>
<p>Semantic UI uses css variables to let users manage <a href="/usage/theming.html">user themed</a> versions of components. Build tools are included in Semantic UI to help compile themed files for your project.</p>
<p>The easiest way to install Semantic UI is our NPM package which contains special install scripts to make setup and updates seamless.</p>
<p>Semantic UI packaged Gulp build tools so your project can preserve its <a href="/usage/theming.html">own theme changes</a>.</p>
<p>The easiest way to install Semantic UI is our NPM package which contains special install scripts to make setup interactive and updates seamless.</p>
<p>For installing with specific integrations like, Ember, React, or Meteor, see our <a href="/introduction/integrations.html">integration guide</a></p>
<p>For integrating Semantic UI tasks into your own build tools see our <a href="/introduction/advanced-usage.html">advanced usage</a> section.</p>
<p><code>2.0</code> includes additional named colors olive, violet, brown and grey which help provide more expressiveness with color variations.</p>
<h4 class="ui header">Complete Spectrum</h4>
<p>Semantic now includes twelve named colors, enough for most languages to <a href="https://en.wikipedia.org/wiki/Linguistic_relativity_and_the_color_naming_debate#Berlin_and_Kay" target="_blank">distinguish between colors</a>. New in 2.0 are: olive, violet, brown and grey.</p>
<a class="ui grey label">Grey</a>
<a class="ui red pointing label">Red</a>
<a class="ui orange tag label">Orange</a>
@ -82,6 +82,15 @@ type : 'Main'
</div>
</div>
</div>
<div class="example">
<h4 class="ui header">New Default Theme</h4>
<p>All components have received a face-lift for 2.0. Styles give slightly more negative space and a few idiosyncratic design touches have been removed.</p>
</div>
<div class="example">
<h4 class="ui header">More Precise EM Values</h4>
<p>EM sizing has been improved in 2.0, with all values rounding to exact pixel values. This helps common relative sizing pitfalls like rounding errors in vertical alignment.</p>
</div>
<h2 class="ui dividing header">Grids</h2>
@ -264,7 +273,7 @@ type : 'Main'
</div>
<div class="dropdown example">
<h4 class="ui header">Scrolling and Nested Menus</h4>
<h4 class="ui header">Scrolling Menus</h4>
<p><a href="modules/dropdown.html#scrolling">Scrolling menu</a> and nested menus are now supported.</p>
<p>Listing choices in a nested menu will still give all the same keyboard shortcuts and filtering as regular menus.</p>
<p>Form now include custom styling for browser <a href="https://developers.google.com/web/fundamentals/input/form/label-and-name-inputs?hl=en">autocompleted form fields</a>. Autocompleted fields can also specify focused autocomplete, and errored autocomplete styles.</p>
<p>Modals can specify additional variations like <code>blurring</code> or <code>inverted</code> which adjust how the dimmer displays.</p>
<div class="code" data-demo="true">
$('.small.modal')
.modal({
inverted: true
})
.modal('show')
;
</div>
<div class="code" data-demo="true">
$('.small.modal')
.modal({
blurring: true
})
.modal('show')
;
</div>
</div>
<div class="no example">
<h4 class="ui header">Scrolling Modal</h4>
<p>When your modal content exceeds the height of the browser the scrollable area will automatically expand to include just enough space for scrolling, without scrolling the page below.</p>
<p>Instead of having to create components from a blank canvas, developers using Semantic UI only need to specify how their components should differ from the default theme using <a href="http://lesscss.org/features/#variables-feature" target="_blank">CSS variables</a>.</p>
</div>
<h2 class="ui dividing header">
Themes
Examples
</h2>
<div class="no example">
<h3 class="ui header">Parts of a Theme</h3>
<h4>Global Inheritance</h4>
<p>Themes are made up of two files a <code>.variables</code> file and a <code>.overrides</code> file.</p>
<p>Semantic UI includes twelve named colors. Components with color variations inherit these global variables when defining how colors should appear.</p>
<p>A <b>.variables</b> file specifies variables which should be adjusted for a theme.</p>
<p>Each level of inheritance can includes a global file <code>site.variables</code> which can define theme-wide defaults that each component can extend.</p>
<p>An <b>.overrides</b> file adds additional css rules from the baseline definition which should be included with an element. This file also has access to all inherited variables for a component.</p>
<div class="description">Theme called "theme-name"</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<p>Packaged themes are themes bundled together in a folder for distribution. These can be downloaded from the internet, or passed between projects.</p>
<p>Packaged themes are specified by name in your <a href="#theme-config">theme.config</a> file.</p>
</div>
<div class="no example">
<h4 class="ui header">Site Theme</h4>
<p><code>src/site/{type}/{element}</code></p>
<div class="ui list">
<div class="item">
<i class="folder icon"></i>
<div class="content">
<div class="header">src</div>
<div class="list">
<div class="item">
<i class="folder icon"></i>
<div class="content">
<div class="header">themes</div>
<div class="description"></div>
<div class="list">
<div class="item">
<i class="folder icon"></i>
<div class="content">
<div class="header">github</div>
<div class="description">Theme called "github"</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<p>A site theme, not to be mistaken with <code>site.variables</code> a file located in every theme, is a special user theme that can be loaded on top of all other themes.</p>
<p>This is the best location to store changes that will be used on a single site. A site theme can be thought of as similar to a <a href="https://codex.wordpress.org/Child_Themes" target="_blank">child theme</a> in Wordpress.</p>
<p>Theme files <b>are optional includes</b> and can be safely removed if you do not need to add additional changes to a component your project</p>
</div>
<div class="no example">
<h4 class="ui header">Definition File</h4>
<p>Each component includes a source css and javascript file which declares how a components variables should affect its display on screen.</p>
<p>Navigating definition files are a great way for developers who are comfortable with css to get an idea of how themes affect a components display</p>
<p>Here's an abridged version of <a href="/elements/button.html">button</a> with an explanation of each section of the file.</p>
<p>Themes are made up of two files a <code>.variables</code> file and a <code>.overrides</code> file. A theme can include both variables and overrides, or just either one alone.</p>
<p>A <b>.variables</b> file specifies variables which should be adjusted for a theme.</p>
<p>An <b>.overrides</b> file adds additional css rules from the baseline definition which should be included with an element. This file also has access to all inherited variables for a component.</p>
<p>Theme files correspond to the name of the component, for example button's site theme would be located at <code>src/site/elements/button.variables</code></p>
</div>
<div class="no example">
<h4 class="ui header">File Locations</h4>
@ -129,55 +416,4 @@ type : 'Usage'
</div>
</div>
<h2 class="ui dividing header">
Examples
</h2>
<div class="no example">
<h4>A Simple Example</h4>
<p>Semantic UI includes thirteen named colors. Components with <code>color variations</code> inherit these global variables when defining how colors should appear.</p>
<p>Most websites will use a different definition of how these colors should appear. Each theme includes a global file <code>site.variables</code> which can be used to define global variables that each component can use or extend.</p>
Jack Lukic
9 years ago