From: Nicolas Coden Date: Sat, 16 Jun 2018 07:10:40 +0000 (+0200) Subject: Use pull request #10847 from ncoden/docs/improve-installation-and-setup-10843 for... X-Git-Tag: v6.5.0-rc.1^2~163 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9e0769e7e84dd2aa28b4d2b9e481ddf52cc85993;p=thirdparty%2Ffoundation%2Ffoundation-sites.git Use pull request #10847 from ncoden/docs/improve-installation-and-setup-10843 for v6.5.0 70543fa0b docs: improve docs of Template installation 8d730a953 docs: improve design of download part in installation 52447aa78 docs: move html starter template to the bottom 20efaa040 docs: add float, prototyping and rtl to CDN links c8b5c029b docs: improve file tree design in installation c47d70b78 docs: improve docs of CLI installation ed5cb75b7 docs: improve design of package manager installation 533b1fa95 docs: add yarn installation to docs 4495764a1 docs: add links to packages managers in installation ac4544977 docs: merge CLI and template installations 030611f4a docs: improve documentation of Starter Projects Signed-off-by: Nicolas Coden --- diff --git a/docs/assets/img/icons/logo-bower.svg b/docs/assets/img/icons/logo-bower.svg new file mode 100755 index 000000000..f76149c0c --- /dev/null +++ b/docs/assets/img/icons/logo-bower.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/img/icons/logo-composer.svg b/docs/assets/img/icons/logo-composer.svg new file mode 100644 index 000000000..96d276434 --- /dev/null +++ b/docs/assets/img/icons/logo-composer.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/img/icons/logo-meteor.svg b/docs/assets/img/icons/logo-meteor.svg new file mode 100755 index 000000000..7d120ceeb --- /dev/null +++ b/docs/assets/img/icons/logo-meteor.svg @@ -0,0 +1 @@ + diff --git a/docs/assets/img/icons/logo-npm.svg b/docs/assets/img/icons/logo-npm.svg new file mode 100644 index 000000000..4330983db --- /dev/null +++ b/docs/assets/img/icons/logo-npm.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/img/icons/logo-nuget.svg b/docs/assets/img/icons/logo-nuget.svg new file mode 100644 index 000000000..148a5e166 --- /dev/null +++ b/docs/assets/img/icons/logo-nuget.svg @@ -0,0 +1,20 @@ + + + + + logo_nuget + + + + + + + \ No newline at end of file diff --git a/docs/assets/img/icons/logo-yarn.svg b/docs/assets/img/icons/logo-yarn.svg new file mode 100755 index 000000000..1aa48bc53 --- /dev/null +++ b/docs/assets/img/icons/logo-yarn.svg @@ -0,0 +1 @@ +Artboard 7 \ No newline at end of file diff --git a/docs/assets/scss/content/_install.scss b/docs/assets/scss/content/_install.scss new file mode 100644 index 000000000..bb5b79946 --- /dev/null +++ b/docs/assets/scss/content/_install.scss @@ -0,0 +1,4 @@ +.docs-install-vendor-icon { + min-height: rem-calc(64px); + max-width: rem-calc(64px); +} diff --git a/docs/assets/scss/docs.scss b/docs/assets/scss/docs.scss index 5875c495f..f0446902b 100644 --- a/docs/assets/scss/docs.scss +++ b/docs/assets/scss/docs.scss @@ -23,6 +23,7 @@ $foundation-dark: #074E68 ; $true-white: #fff; @import 'foundation-docs'; +@import 'content/install'; @import 'examples/grid'; @import 'examples/motion-ui'; @import 'examples/off-canvas'; diff --git a/docs/pages/installation.md b/docs/pages/installation.md index fd2bcd6c5..d3990cc52 100644 --- a/docs/pages/installation.md +++ b/docs/pages/installation.md @@ -4,89 +4,227 @@ description: There are many ways to install Foundation, but if you're just getti video: '6KwsGcEHVTE' --- -### Command-Line Tool +## Install with Package Managers -Not a fan of GUIs? The Node-powered Foundation CLI can install the same template projects for you. Install it with npm: +Foundation is available on npm, Bower, Meteor, and Composer. The package includes all of the source Sass and JavaScript files, as well as compiled CSS and JavaScript, in uncompressed and compressed flavors. + +
+
+ + NPM + +
+
+
+ + npm install foundation-sites + +
+
+ +
+ + Yarn + +
+
+
+ + yarn install foundation-sites + +
+
+ +
+ + Bower + +
+
+
+ + bower install foundation-sites + +
+
+ +
+ + Meteor + +
+
+
+ + meteor add zurb:foundation-sites + +
+
+ +
+ + Composer + +
+
+
+ + php composer.phar require zurb/foundation + +
+
+ +
+ + NuGet + +
+
+
+ + Install-Package foundation-sites + +
+
+
+ +Here's what comes in the package. -```bash -npm install --global foundation-cli +``` +├─ scss Source Sass files. Use this folder as a load path in Sass. +├─ js Source JavaScript files. If you're using a build system, make sure `foundation.core.js` is loaded first. +└─ dist Compiled files: + ├─ css * Compiled CSS files. Includes minified and unminified files. + ├─ js * Concatenated JavaScript files. Includes minified and unminified files. + └─ plugins * Standalone JavaScript plugins. ``` -Depending on how your machine is configured, the command may fail with an `EACCESS` error. To get around this, run the command with `sudo` at the beginning: +--- + +## Install with Foundation CLI + +Not a fan of GUIs? The Node-powered Foundation CLI can install the same template projects for you. + +Install Foundation CLI: ```bash -sudo npm install --global foundation-cli +npm install --global foundation-cli +# or sudo npm install --global foundation-cli ``` -
-

If you already have the Foundation 5 CLI on your machine, you will only be able to access one of the commands, depending on how your command line environment is configured.

- -

If you want to remove the old CLI, run gem uninstall foundation. After testing this new CLI, if you want to go back to the old CLI, run npm uninstall foundation-cli --global.

+
+ Depending on how your machine is configured, the command may fail with an `EACCESS` error. To get around this, run the commands with `sudo` at the beginning.
-Once you've installed the CLI, use the `new` command to start making a new project: +Then use to create a new Foundation project: ```bash foundation new ``` ---- +After you selected "Foundation for Sites", Foundation CLI will ask you which template you want to use. You can choose between: + +
+
+

Basic template

+

+ Recommended for beginners
+ A basic template to begin to use Foundation. It includes: +

    +
  • + Foundation for Sites pre-configured. +
    • +
  • + Sass compilation
    + A tool to convert your SASS/SCSS files to CSS. +
    • +
  • + Starter HTML file
    + A basic file to help you to use basic Foundation component (including the new XY grid !) +
    • +
+

+
+ +
+

ZURB template

+

+ Recommended for experienced (or curious) users
+ A more advanced project including Foundation and a build process with: +

    +
  • Handlebars HTML templates with Panini
    • +
  • Sass compilation and prefixing
    • +
  • JavaScript module bundling with webpack
    • +
  • Built-in BrowserSync
    • +
  • Production build with CSS, Javascript and Image compression
    • +
+

+
+
-## Manual Setup +

+ See advanced Template installations +

-### Basic Template +
+

Foundation 5 users: if you already have the Foundation 5 CLI on your machine, you will only be able to access one of the commands, depending on how your command line environment is configured.

-To manually set up the basic template, first download it with Git: +

To remove the Foundation 5 CLI, run gem uninstall foundation. After testing this new CLI, if you want to go back to the old CLI. To remove the Foundation 6 CLI, run npm uninstall foundation-cli --global.

+
-```bash -git clone https://github.com/zurb/foundation-sites-template projectname -``` +--- -Then open the folder in your command line, and install the needed dependencies: +## Download + +
+
+
+ + +
+
+ +
+

+ If you aren't into Sass, we have a starter template with compiled CSS and JavaScript, as well as a starting `index.html` file for you to hack on. Just unzip and get coding! +

+

+ Download Foundation +

+
+
-```bash -cd projectname -npm install -``` +--- -Finally, run `npm start` to run the Sass compiler. It will re-run every time you save a Sass file. +## CDN Links -### ZURB Template +The folks at [cdnjs](https://cdnjs.com) host the compressed Foundation CSS and JavaScript for us. Just drop one of these ` ``` -Then open the folder in your command line, and install the needed dependencies: +From Foundation 6.4, flex is enabled by default and **only the new XY Grid is availaible**. However, others CSS versions are availaible for backward compatibility and the msot common usage cases. For others uses and advanced customization, we recommand to build Foundation with custom settings (see others installation methods). -```bash -cd projectname -npm install -``` +```html + + -Finally, run `npm start` to run Gulp. Your finished site will be created in a folder called `dist`, viewable at this URL: + + -``` -http://localhost:8000 + + ``` -To create compressed, production-ready assets, run `npm run build`. - ---- - -## CSS Download - -
- - +
+ See all CDN files and versions
-If you aren't into Sass, we have a starter template with compiled CSS and JavaScript, as well as a starting `index.html` file for you to hack on. Just unzip and get coding! - -Download CSS Version - --- ## HTML Starter Template @@ -119,43 +257,6 @@ Start with this HTML template and adapt it to your needs. Be sure to include the --- -## CDN Links - -The folks at [cdnjs](https://cdnjs.com) host the compressed Foundation CSS and JavaScript for us. Just drop one of these ` -``` - ---- - -## Package Managers - -Foundation is available on npm, Bower, Meteor, and Composer. The package includes all of the source Sass and JavaScript files, as well as compiled CSS and JavaScript, in uncompressed and compressed flavors. - -- npm: `npm install foundation-sites` -- Bower: `bower install foundation-sites` -- Meteor: `meteor add zurb:foundation-sites` -- Composer: `php composer.phar require zurb/foundation` -- NuGet: `Install-Package foundation-sites` - -### Package Contents - -Here's what comes in the package. - -- `scss/`: Source Sass files. Use this folder as a load path in Sass. -- `js/`: Source JavaScript files. If you're using a build system, make sure `foundation.core.js` is loaded first. -- `dist/`: Compiled files. - - `css/`: Compiled CSS files. Includes minified and unminified files. - - `js/`: Concatenated JavaScript files. Includes minified and unminified files. - - `plugins/`: Standalone JavaScript plugins. - ---- - ## Other Integrations The Foundation community has helped us integrate the framework into Rails, WordPress, Django, and more. Head to our [resources page](http://foundation.zurb.com/sites/resources) to find even more ways to use Foundation. diff --git a/docs/pages/starter-projects.md b/docs/pages/starter-projects.md index eb9a2dd52..65bdf8575 100644 --- a/docs/pages/starter-projects.md +++ b/docs/pages/starter-projects.md @@ -4,6 +4,7 @@ description: We have a few starter project templates that can be installed with video: 'lFrpnk0Oo_8' --- + Our project templates give you a solid... *Foundation* on which to start a new project. Both templates use the [Gulp](http://gulpjs.com) build system to automate the process of compiling Sass, processing JavaScript, copying files, and more. ## Basic Template @@ -21,11 +22,24 @@ You can set up a basic project through the Foundation CLI with this command: foundation new --framework sites --template basic ``` -It's also possible to download the template files directly from GitHub. Run `npm install` and `bower install` first to set it up, then `npm start` to run it. [Download basic template](https://github.com/zurb/foundation-sites-template/archive/master.zip). +You can manually install the template with: + ```bash +# Download the template with Git +git clone https://github.com/zurb/foundation-sites-template projectname + +# Move to the project folter, and install dependencies +cd projectname +npm install + +# Build the Sass files +npm start +``` + +Your project will be recompiled every time you save a Sass file in `dist/. --- -## ZURB Stack (Template) +## ZURB Template
@@ -40,7 +54,21 @@ You can set up an advanced project through the Foundation CLI with this command: foundation new --framework sites --template zurb ``` -It's also possible to download the template files directly from GitHub. Run `npm install` first to set it up, then `npm start` to run it. [Download advanced template](https://github.com/zurb/foundation-zurb-template/archive/master.zip). +You can manually install the template with: +```bash +# Download the ZURB template with Git +git clone https://github.com/zurb/foundation-zurb-template projectname + +# Move to the project folter, and install dependencies +cd projectname +npm install +bower install + +# Build the project +npm start +``` + +Once compiled, you project is viewable at: http://localhost:8000 The biggest difference between this and the basic template is the folder structure. In the ZURB Template, your project has a `src/` folder which contains your source files, and a separate `dist/` folder with your finished website. As you work on your project, Gulp continuously updates your `dist/` folder with new versions of files. To compile a production build, run `npm run build`. @@ -50,43 +78,46 @@ To override or add to the default styles of the ZURB Template, in your project's The `_settings.scss` and `app.scss` files are not changed when upgrading an existing project. As a result, you must manually edit your `_settings.scss` file to incorporate any Sass changes found [in the release notes](https://github.com/zurb/foundation-sites/releases). +### Features + Here's an overview of what the ZURB Template can do: -### Asset Copying +* **Asset Copying** -Gulp will copy anything out of the `src/assets` folder as-is to the `assets` folder of your final project. Note that Sass files, JavaScript files, and images are *not* part of this copying process, as they have their own steps. + Gulp will copy anything out of the `src/assets` folder as-is to the `assets` folder of your final project. Note that Sass files, JavaScript files, and images are *not* **part of this copying process, as they have their own steps.** + -### Page Compilation +* **Page Compilation** -The `src/` directory includes three folders used to create HTML pages: `pages/`, `layouts/`, and `partials/`. A flat file compiler called [Panini](panini.html) is used to process your project's various pages, inserting them into a common template, and injecting any HTML partials. This is done with a templating language called [Handlebars](http://handlebarsjs.com/). + The `src/` directory includes three folders used to create HTML pages: `pages/`, `layouts/`, and `partials/`. A flat file compiler called [Panini](panini.html) is used to process your project's various pages, inserting them into a common template, and injecting any HTML partials. This is done with a templating language called [Handlebars](http://handlebarsjs.com/). -Panini has a dedicated page here in the docs that explains its various features. **[Learn more about Panini.](panini.html)** + Panini has a dedicated page here in the docs that explains its various features. **[Learn more about Panini.](panini.html)** -### Sass Compilation +* **Sass Compilation** -Sass is compiled to CSS using [Libsass](http://sass-lang.com/libsass) (via [node-sass](https://github.com/sass/node-sass)). The main Sass file is under `src/assets/scss/app.scss`, and imports Foundation and Motion UI. Any new Sass partials you create should be in this folder as well. + Sass is compiled to CSS using [Libsass](http://sass-lang.com/libsass) (via [node-sass](https://github.com/sass/node-sass)). The main Sass file is under `src/assets/scss/app.scss`, and imports Foundation and Motion UI. Any new Sass partials you create should be in this folder as well. -The CSS is output in the `nested` style, which is readable like normal CSS. A source map is also created, which can be read by developer tools such as the Chrome Web Inspector. When building for production, the CSS is also compressed with [clean-css](https://github.com/jakubpawlowicz/clean-css/issues), and pruned with [UnCSS](https://github.com/giakki/uncss). UnCSS scans the HTML of your pages and removes any CSS classes you didn't use. + The CSS is output in the `nested` style, which is readable like normal CSS. A source map is also created, which can be read by developer tools such as the Chrome Web Inspector. When building for production, the CSS is also compressed with [clean-css](https://github.com/jakubpawlowicz/clean-css/issues), and pruned with [UnCSS](https://github.com/giakki/uncss). UnCSS scans the HTML of your pages and removes any CSS classes you didn't use. -### JavaScript Compilation +* **JavaScript Compilation** -All JavaScript files in the `src/assets/js` folder, along with Foundation and its dependencies, are bundled into one file called `app.js`. The files are imported using module dependency with [webpack](https://webpack.js.org/) as the module bundler. + All JavaScript files in the `src/assets/js` folder, along with Foundation and its dependencies, are bundled into one file called `app.js`. The files are imported using module dependency with [webpack](https://webpack.js.org/) as the module bundler. -If you're unfamiliar with modules and module bundling, check out [this resource for node style require/exports](http://openmymind.net/2012/2/3/Node-Require-and-Exports/) and [this resource to understand ES6 modules](http://exploringjs.com/es6/ch_modules.html) + If you're unfamiliar with modules and module bundling, check out [this resource for node style require/exports](http://openmymind.net/2012/2/3/Node-Require-and-Exports/) and [this resource to understand ES6 modules](http://exploringjs.com/es6/ch_modules.html) -A source map is created that maps back to the original files. By default, the bundled `app.js` is uncompressed. When building for production, the file is run through [UglifyJS](https://github.com/mishoo/UglifyJS) for compression. + A source map is created that maps back to the original files. By default, the bundled `app.js` is uncompressed. When building for production, the file is run through [UglifyJS](https://github.com/mishoo/UglifyJS) for compression. -### Image Compression +* **Image Compression** -By default, all images are copied as-is from `assets/img` to your `dist` folder. When building for production, images are run through [gulp-imagemin](https://github.com/sindresorhus/gulp-imagemin) for compression. The plugin supports JPEG, PNG, SVG, and GIF files. + By default, all images are copied as-is from `assets/img` to your `dist` folder. When building for production, images are run through [gulp-imagemin](https://github.com/sindresorhus/gulp-imagemin) for compression. The plugin supports JPEG, PNG, SVG, and GIF files. -### BrowserSync +* **BrowserSync** -The template creates a [BrowserSync](http://www.browsersync.io/) server, which is at `http://localhost:8000`. Load this URL to see your compiled templates. While the server is running, any time you save a file, any pages you have open will automatically refresh, allowing you to see changes in real-time as you work. + The template creates a [BrowserSync](http://www.browsersync.io/) server, which is at `http://localhost:8000`. Load this URL to see your compiled templates. While the server is running, any time you save a file, any pages you have open will automatically refresh, allowing you to see changes in real-time as you work. -### Style Guide Creation +* **Style Guide Creation** -Under `src/styleguide` are two files to create a style guide for your project. The style guide is generated using Style Sherpa, a small plugin created by ZURB. + Under `src/styleguide` are two files to create a style guide for your project. The style guide is generated using Style Sherpa, a small plugin created by ZURB. Style Sherpa has a dedicated page here in the docs that explains its various features. **[Learn more about Style Sherpa.](style-sherpa.html)**