Documentation for the Datacenter Operating System (DC/OS)
These documents are used as source to generate dev.dcos.io/docs (staging) and dcos.io/docs (production). They are submoduled into dcos-website for deployment.
Issue tracking is moving to the DCOS JIRA (docs component). Issues on Github will be disabled soon.
- Styling and formatting your contribution
- Making your contribution
- Building and testing your content locally
- Submitting your pull request
-
Use relative links.
-
Begin all links at the root
docs
level and include the version number subdirectory. (e.g.,/docs/1.8/administration/access-node/sshcluster/
). -
Each directory must contain an
index.md
file. This acts as the base-level topic for each folder in the site (required). -
Do not include file names in your paths. Our site converts any files not named
index.md
into directory names. For example, the directory/docs/1.8/administration/
contains a file nameduser-management.md
. To link to this content on the live site, you would use the following path:/docs/1.8/administration/user-management/
. -
The table of contents of each page is automatically generated based on the top-level headers.
-
Directory tables of contents are automatically generated based on
post_title
(ornav_title
) andpost_excerpt
headers. -
Use active voice whenever possible.
-
Use sentence-style capitalization for headings.
-
Create a JIRA issue and select docs as the component.
-
Clone your fork of the dcos-docs repo.
$ git clone https://github.com/<your-user-name>/dcos-docs
-
Create a branch on your fork using your JIRA number as the name.
$ git checkout -b dcos-nnn
-
Create your content. In most cases you should be able to create your content within the existing directory structure.
-
To create a single page:
-
Create a markdown file
{post_slug}.md
wherepost_slug
is your file name. File names become URIs. If you want this page to be a child of another page, place the.md
file in the parent folder. -
Add your page content, including the required metadata
post_title
and optionalnav_title
andmenu_order
. Do not include any other metadata.``` --- post_title: The Title --- Post markdown goes here. ```
-
-
To create a page with hierarchy:
-
Create a new directory in the appropriate location of the correctly versioned release (e.g.,
/1.8/foo
) and a child page within this folder namedindex.md
(e.g./1.8/foo/index.md
). The actual URI of your page will be/1.8/foo/
, not/1.8/foo/index
. For example, if it's a tutorial for 1.7, create a new directory here/1.8/usage/tutorials/foo/
. -
Add your page content, including the required metadata
post_title
and optionalnav_title
andmenu_order
. Where applicable, add thefeature_maturity
label. Description of various feature maturity phases can be found here: https://dcos.io/docs/1.8/overview/feature-maturity/. Do not include any other metadata.```bash --- post_title: The Title feature_maturity: preview --- Post markdown goes here. ```
-
-
Tips:
-
Check the
templates
directory to see if there is a template that corresponds to the type of content you are creating. For example, if it's a tutorial you can copy templates/tutorial.md intofoo/
and rename it tofoo/index.md
. Adapt the sections in your newfoo/index.md
to the specifics of your content. -
Add images in a child
foo/img/
directory. -
Include all required assets in your
/foo
directory, for example, Marathon app spec, JSON docs, or a Dockerfile. -
If you're unsure about what exactly should go into a tutorial, you can always check out spark/ for reference.
-
-
-
Push your changes into the feature branch of your remote.
$ git add . $ git commit -m "Addresses issue DCOS-nnn" $ git push origin dcos-nnn
This method builds and launches a Docker container. For more information, see this PR.
Prerequisite: Latest version of Docker installed and running.
-
Run
sudo make
.Tip: This can take up to 15 minutes to complete.
-
Visit localhost
- If your build fails with an error (e.g.
npm ERR! /website/npm-debug.log
), try deleting the/dcos-docs/tmp
directory and re-running themake
command.
We've implemented the dcos-docs repo as a submodule of the dcos-website repo. Before submitting your pull request against the dcos-docs repo, fork the parent dcos-website repo and build the site locally. This will allow you to confirm that your content renders correctly and that all of your links work.
-
Install the prerequisites:
-
-
CentOS
$ sudo yum install -y ruby
-
MacOS using Homebrew
$ brew install ruby
-
-
-
CentOS
$ sudo yum install git
-
MacOS using Homebrew
$ brew install git
-
-
Install EPEL repo, Node, and NPM.
-
CentOS
$ sudo yum install -y epel-release && sudo yum install -y nodejs && sudo yum install -y npm && npm update
-
MacOS using Homebrew
$ brew install -y nodejs $ brew install npm $ npm update
-
-
nvm 6.3.1
-
CentOS
$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.4/install.sh | bash $ nvm install 6.3.1 && nvm alias default 6.3.1
-
MacOS
$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.4/install.sh | bash $ nvm install 6.3.1 && nvm alias default 6.3.1
-
-
-
CentOS
$ sudo npm install --global gulp-cli
-
MacOS
$ npm install --global gulp-cli
-
-
-
Clone the dcos-website repo.
$ git clone https://github.com/dcos/dcos-website
-
Check out the develop branch of
dcos-website
.$ git checkout develop
-
Initialize the
dcos-docs
submodule with the content from the upstream master.$ git submodule update --init --recursive
Optional: replace the content from the upstream master with the content from your local
dcos-docs
repo. Delete thedcos-website/dcos-dcos
directory and replace it with a symlink to your localdcos-docs
repo. For example, if your directory structure is/projects/dcos-website
and/projects/dcos-docs
, you can issue these commands from thedcos-website
directory:$ rm -r dcos-docs $ ln -s <local-path-to-dcos-docs> dcos-docs
-
Launch the local web server to view your changes.
$ npm start
-
When you're done, submit a pull request against the dcos-docs repo.
-
Add a link to this PR in your JIRA issue.
For all contributions that include hands-on instructions, such as found in usage/
or administration/
, the community managers will test-drive and validate before merging. They might come back to you asking you to fix things. All communications should take place within your pull request on GitHub.
Copyright 2016 Mesosphere, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this repository except in compliance with the License.
The contents of this repository are solely licensed under the terms described in the LICENSE file included in this repository.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Authors are listed in AUTHORS.md file.