-
Notifications
You must be signed in to change notification settings - Fork 56
docs: Add getting started>download page #2908
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.
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
Merged
vprothais
merged 13 commits into
ouds/main
from
ouds/main-2900-docs-add-getting-started-download-page
Apr 2, 2025
Merged
Changes from 8 commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
d30b847
Restored from Bootstrap
hannahiss cf538de
Start adapting to OUDS Web
hannahiss e4fa7a1
unpkg url
hannahiss 7181f62
make sure callout generate a <p> everywhere + update links in downloa…
hannahiss 20dcecb
Remove comments and todos
hannahiss f57d7e4
Replace cndjs link by unpkg
hannahiss b414f11
adaptations after Maxime's review
hannahiss dc99876
Merge branch 'ouds/main' into ouds/main-2900-docs-add-getting-started…
hannahiss ad18f1f
Merge branch 'ouds/main' into ouds/main-2900-docs-add-getting-started…
hannahiss c499789
Remove composer
hannahiss a511cde
Merge branch 'ouds/main' into ouds/main-2900-docs-add-getting-started…
vprothais b2eac0b
link bootstrap example inside our doc
hannahiss 7404a20
Merge branch 'ouds/main' into ouds/main-2900-docs-add-getting-started…
vprothais File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,139 @@ | ||
--- | ||
layout: docs | ||
title: Download | ||
description: Download OUDS Web to get the compiled CSS and JavaScript, source code, or include it with your favorite package managers like npm, RubyGems, and more. | ||
description: Download OUDS Web to get the compiled CSS and JavaScript, source code, or include it with your favorite package managers like npm, yarn, and more. | ||
group: getting-started | ||
aliases: | ||
- "/docs/getting-started/download/" | ||
toc: true | ||
--- | ||
|
||
{{< callout-soon "page" >}} | ||
## Package managers | ||
|
||
Pull in OUDS Web’s **source files** into nearly any project with some of the most popular package managers. No matter the package manager, OUDS Web will **require a [Sass compiler]({{< docsref "/getting-started/contribute#sass" >}}) and [Autoprefixer]({{< docsref "/getting-started/contribute#autoprefixer" >}})** for a setup that matches our official compiled versions. | ||
|
||
### npm | ||
|
||
Install OUDS Web in your Node.js powered apps with [the npm package](https://www.npmjs.com/package/@ouds/web): | ||
|
||
```sh | ||
npm install @ouds/web@{{< param "current_version" >}} | ||
``` | ||
|
||
`const oudsWeb = require('oudsWeb')` or `import oudsWeb from 'oudsWeb'` will load all of OUDS Web's plugins onto a `oudsWeb` object. | ||
The `oudsWeb` module itself exports all of our plugins. You can manually load OUDS Web's plugins individually by loading the `/js/dist/*.js` files under the package's top-level directory. | ||
|
||
OUDS Web's `package.json` contains some additional metadata under the following keys: | ||
|
||
- `sass` - path to OUDS Web's main [Sass](https://sass-lang.com/) source file | ||
- `style` - path to OUDS Web's non-minified CSS that's been compiled using the default settings (no customization) | ||
|
||
{{< callout info >}} | ||
{{< partial "callouts/info-npm-starter.md" >}} | ||
{{< /callout >}} | ||
|
||
### yarn | ||
|
||
Install OUDS Web in your Node.js powered apps with [the yarn package](https://yarnpkg.com/en/package/@ouds/web): | ||
|
||
```sh | ||
yarn add @ouds/web@{{< param "current_version" >}} | ||
``` | ||
|
||
{{< callout warning >}} | ||
**Yarn 2+ (aka Yarn Berry) doesn't support the `node_modules` directory by default**: using the Bootstrap [Sass & JS example](https://github.com/twbs/examples/tree/main/sass-js) needs some adjustments: | ||
```sh | ||
yarn config set nodeLinker node-modules # Use the node_modules linker | ||
touch yarn.lock # Create an empty yarn.lock file | ||
yarn install # Install the dependencies | ||
yarn start # Start the project | ||
``` | ||
{{< /callout >}} | ||
|
||
### Composer | ||
|
||
You can also install and manage OUDS Web's Sass and JavaScript using [Composer](https://getcomposer.org/): | ||
|
||
```sh | ||
composer require orange-opensource/orange-boosted-bootstrap:{{< param current_version >}} | ||
``` | ||
vprothais marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
### NuGet | ||
|
||
If you develop in .NET Framework, you can also install and manage OUDS Web's [CSS](https://www.nuget.org/packages/ouds-web) or [Sass](https://www.nuget.org/packages/ouds-web.sass) and JavaScript using [NuGet](https://www.nuget.org/). Newer projects should use [libman](https://learn.microsoft.com/en-us/aspnet/core/client-side/libman/) or another method as NuGet is designed for compiled code, not frontend assets. | ||
|
||
```powershell | ||
Install-Package ouds-web | ||
``` | ||
|
||
```powershell | ||
Install-Package ouds-web.sass | ||
``` | ||
|
||
## CDNs | ||
|
||
### jsDelivr | ||
|
||
We recommend [jsDelivr](https://www.jsdelivr.com/package/npm/@ouds/web/) as a CDN, and use it ourselves in our documentation to skip the download and deliver cached version of OUDS Web's compiled CSS and JS to your project. | ||
|
||
```html | ||
<link href="https://cdn.jsdelivr.net" rel="preconnect" crossorigin="anonymous"> | ||
<link href="{{< param "cdn.css" >}}" rel="stylesheet" integrity="{{< param "cdn.css_hash" >}}" crossorigin="anonymous"> | ||
<script src="{{< param "cdn.js_bundle" >}}" integrity="{{< param "cdn.js_bundle_hash" >}}" crossorigin="anonymous"></script> | ||
``` | ||
|
||
If you're using our compiled JavaScript and prefer to include Popper separately, add Popper before our JS, via a CDN preferably. | ||
|
||
```html | ||
<script src="{{< param "cdn.popper" >}}" integrity="{{< param "cdn.popper_hash" >}}" crossorigin="anonymous"></script> | ||
<script src="{{< param "cdn.js" >}}" integrity="{{< param "cdn.js_hash" >}}" crossorigin="anonymous"></script> | ||
``` | ||
|
||
{{< callout warning >}} | ||
**Resource hint**: make sure to use [`preconnect`](https://developer.mozilla.org/docs/Web/HTML/Attributes/rel/preconnect) where appropriate (**only** when given URL **will** be used). | ||
{{< /callout >}} | ||
|
||
### Alternative CDN | ||
|
||
In some cases—like in some specific countries or environments—you may need to use other CDN providers like [unpkg](https://www.unpkg.com/browse/@ouds/web@{{< param "current_version" >}}). You'll find the same files on these CDN providers, albeit with different URLs. | ||
|
||
{{< callout warning>}} | ||
**If the SRI hashes differ for a given file, you shouldn't use the files from that CDN, because it means that the file was modified by someone else.** | ||
{{< /callout >}} | ||
|
||
Note that you should compare same length hashes, e.g. `sha384` with `sha384`, otherwise it's expected for them to be different. | ||
As such, you can use an online tool like [SRI Hash Generator](https://www.srihash.org/) to make sure that the hashes are the same for a given file. Alternatively, assuming you have OpenSSL installed, you can achieve the same from the CLI, for example: | ||
|
||
```sh | ||
openssl dgst -sha384 -binary ouds-web.min.js | openssl base64 -A | ||
``` | ||
|
||
vprothais marked this conversation as resolved.
Show resolved
Hide resolved
|
||
## Downloads | ||
|
||
### Compiled CSS and JS | ||
|
||
Download ready-to-use compiled code for **OUDS Web v{{< param current_version >}}** to easily drop into your project, which includes: | ||
|
||
- Compiled and minified CSS bundles (see [CSS files comparison]({{< docsref "/getting-started/contents#css-files" >}})) | ||
- Compiled and minified JavaScript plugins (see [JS files comparison]({{< docsref "/getting-started/contents#js-files" >}})) | ||
|
||
This doesn't include documentation, source files, or any optional JavaScript dependencies like Popper. | ||
|
||
<a href="{{< param "download.dist" >}}" class="btn btn-default" onclick="dataLayer.push({'event': 'clic', 'site_name':'accessibility-boosted', 'phase':'prod', 'track_category':'download', 'track_name':'getting started', 'track_cible':'download source'});">Download</a> | ||
|
||
### Source files | ||
|
||
Compile OUDS Web with your own asset pipeline by downloading our source Sass, JavaScript, and documentation files. This option requires some additional tooling: | ||
|
||
- [Sass compiler]({{< docsref "/getting-started/contribute#sass" >}}) for compiling Sass source files into CSS files | ||
- [Autoprefixer]({{< docsref "/getting-started/contribute#autoprefixer" >}}) for CSS vendor prefixing | ||
|
||
Should you require our full set of [build tools]({{< docsref "/getting-started/contribute#tooling-setup" >}}), they are included for developing OUDS Web and its docs, but they're likely unsuitable for your own purposes. | ||
|
||
<a href="{{< param "download.source" >}}" class="btn btn-default" onclick="dataLayer.push({'event': 'clic', 'site_name':'accessibility-boosted', 'phase':'prod', 'track_category':'download', 'track_name':'getting started', 'track_cible':'download source'});">Download source</a> | ||
|
||
### Examples | ||
|
||
If you want to download and examine our [examples]({{< docsref "/examples" >}}), you can grab the already built examples: | ||
|
||
<a href="{{< param "download.dist_examples" >}}" class="btn btn-default" onclick="dataLayer.push({'event': 'clic', 'site_name':'accessibility-boosted', 'phase':'prod', 'track_category':'download', 'track_name':'getting started', 'track_cible':'download examples source'});">Download examples</a> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,2 @@ | ||
**Bootstrap starter project!** | ||
**Get started with Bootstrap via npm with the starter project!** | ||
Head to the [Sass & JS example](https://github.com/twbs/examples/tree/main/sass-js) template repository to see how to build and customize Bootstrap in your own npm project. Includes Sass compiler, Autoprefixer, Stylelint, PurgeCSS, and Bootstrap Icons. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.