Improved doc editing instructions/sharing with README.md
This commit is contained in:
John Mulhausen
parent
869e7de45a
commit
ba1e511e5a
60
README.md
60
README.md
|
|
@ -1,6 +1,6 @@
|
|||
# Contributing to the Kubernetes Documentation and Website
|
||||
## Instructions for Contributing to the Docs/Website
|
||||
|
||||
Welcome! We are very pleased you want to contribute to Kubernetes.
|
||||
Welcome! We are very pleased you want to contribute to the documentation and/or website for Kubernetes.
|
||||
|
||||
You can click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it.
|
||||
|
||||
|
|
@ -13,7 +13,7 @@ Then, visit: [http://YOUR_GITHUB_USERNAME.github.io](http://YOUR_GITHUB_USERNAME
|
|||
|
||||
You should see a special-to-you version of the site.
|
||||
|
||||
## Running the site locally
|
||||
## Editing/staging the site locally
|
||||
|
||||
If you have files to upload, or just want to work offline, run the below commands to setup
|
||||
your environment for running GitHub pages locally. Then, any edits you make will be viewable
|
||||
|
|
@ -45,12 +45,12 @@ Clone our site
|
|||
|
||||
git clone https://github.com/kubernetes/kubernetes.github.io.git
|
||||
|
||||
Then, to see it run locally:
|
||||
Make any changes you want. Then, to see your changes locally:
|
||||
|
||||
cd kubernetes.github.io
|
||||
jekyll serve
|
||||
|
||||
Your copy of the site will then be viewable at: [http://0.0.0.0:4000](http://0.0.0.0:4000)
|
||||
Your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000)
|
||||
(or wherever Ruby tells you).
|
||||
|
||||
If you're a bit rusty with git/GitHub, you might wanna read
|
||||
|
|
@ -60,6 +60,56 @@ The above instructions work on Mac and Linux.
|
|||
[These instructions ](https://martinbuberl.com/blog/setup-jekyll-on-windows-and-host-it-on-github-pages/)
|
||||
might help for Windows users.
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Edit Page Titles or Change the Left Navigation
|
||||
|
||||
Edit the yaml files in `/_data/` for the Guides, Reference, Samples, or Support areas.
|
||||
|
||||
### Add Images
|
||||
|
||||
Put the new image in `/images/docs/` if it's for the documentation, and just `/images/` if it's for the website.
|
||||
|
||||
### Include code from another file
|
||||
|
||||
To include a file that is hosted on this GitHub repo, insert this code:
|
||||
|
||||
<pre>{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="<PATHFROMROOT>" %}</pre>
|
||||
|
||||
* `LEXERVALUE`: The language in which the file was written; must be [a value supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers).
|
||||
* `RELATIVEPATH`: The path to the file you're including, relative to the current file.
|
||||
* `PATHFROMROOT`: The path to the file relative to root, e.g. `/docs/admin/foo.yaml`
|
||||
|
||||
To include a file that is hosted in the external, main Kubernetes repo, make sure it's added to [/update-imported-docs.sh](https://github.com/kubernetes/kubernetes.github.io/blob/master/update-imported-docs.sh), and run it so that the file gets downloaded, then enter:
|
||||
|
||||
<pre>{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" k8slink="<PATHFROMK8SROOT>" %}</pre>
|
||||
|
||||
* `PATHFROMK8SROOT`: The path to the file relative to the root of [the Kubernetes repo](https://github.com/kubernetes/kubernetes/tree/release-1.2), e.g. `/examples/rbd/foo.yaml`
|
||||
|
||||
## Use a global variable
|
||||
|
||||
The `/_config.yml` file defines some useful variables you can use when editing docs.
|
||||
|
||||
* `page.githubbranch`: The name of the GitHub branch on the Kubernetes repo that is associated with this branch of the docs. e.g. `release-1.2`
|
||||
* `page.version` The version of Kubernetes associated with this branch of the docs. e.g. `v1.2`
|
||||
* `page.docsbranch` The name of the GitHub branch on the Docs/Website repo that you are currently using. e.g. `release-1.1` or `master`
|
||||
|
||||
This keeps the docs you're editing aligned with the Kubernetes version you're talking about. For example, if you define a link like so, you'll never have to worry about it going stale in future doc branches:
|
||||
|
||||
<pre>View the README [here](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/README.md).</pre>
|
||||
|
||||
That, of course, will send users to:
|
||||
|
||||
[http://releases.k8s.io/release-1.2/cluster/addons/README.md](http://releases.k8s.io/release-1.2/cluster/addons/README.md)
|
||||
|
||||
(Or whatever Kubernetes release that docs branch is associated with.)
|
||||
|
||||
## Branch structure
|
||||
|
||||
The current version of the website is served out of the `master` branch.
|
||||
|
||||
All versions of the site that relate to past and future versions will be named after their Kubernetes release number. For example, [the old branch for the 1.1 docs is called `release-1.1`](https://github.com/kubernetes/kubernetes.github.io/tree/release-1.1).
|
||||
|
||||
## Thank you!
|
||||
|
||||
Kubernetes thrives on community participation and we really appreciate your
|
||||
|
|
|
|||
|
|
@ -41,4 +41,4 @@ toc:
|
|||
- title: Release Roadmap
|
||||
path: https://github.com/kubernetes/kubernetes/milestones/
|
||||
- title: Contributing to Kubernetes Documentation
|
||||
path: /docs/editdocs/
|
||||
path: /editdocs/
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@
|
|||
</div> <!-- /pi-accordion -->
|
||||
</div> <!-- /docsToc -->
|
||||
<div id="docsContent">
|
||||
<p><a href="/docs/editdocs#{{ page.path }}" id="editPageButton">Edit This Page</a></p>
|
||||
<p><a href="/editdocs#{{ page.path }}" id="editPageButton">Edit This Page</a></p>
|
||||
{% if notitle != "true" %}<h1>{{ title }}</h1>{% endif %}
|
||||
{{ content }}
|
||||
<p><a href=""><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/{{ page.path }}?pixel" alt="Analytics" /></a>
|
||||
|
|
|
|||
115
docs/editdocs.md
115
docs/editdocs.md
|
|
@ -1,115 +0,0 @@
|
|||
---
|
||||
---
|
||||
Welcome! We are very pleased you want to contribute to the docs for Kubernetes.
|
||||
|
||||
<!-- BEGIN: Gotta keep this section JS/HTML because it swaps out content dynamically -->
|
||||
<p> </p>
|
||||
<script language="JavaScript">
|
||||
var forwarding=window.location.hash.replace("#","");
|
||||
$( document ).ready(function() {
|
||||
if(forwarding) {
|
||||
$("#generalInstructions").hide();
|
||||
$("#continueEdit").show();
|
||||
$("#continueEditButton").text("Edit " + forwarding);
|
||||
$("#continueEditButton").attr("href", "https://github.com/kubernetes/kubernetes.github.io/edit/master/" + forwarding)
|
||||
} else {
|
||||
$("#generalInstructions").show();
|
||||
$("#continueEdit").hide();
|
||||
}
|
||||
});
|
||||
</script>
|
||||
<div id="continueEdit">
|
||||
|
||||
<h2>Continue your edit</h2>
|
||||
|
||||
<p>Click the below link to edit the page you were just on. When you are done, press "Commit Changes" at the bottom of the screen. This will create a copy of our site on your GitHub account called a "fork." You can make other changes in your fork after it is created, if you want. When you are ready to send us all your changes, go to the index page for your fork and click "New Pull Request" to let us know about it.</p>
|
||||
|
||||
<p><a id="continueEditButton" class="button"></a></p>
|
||||
|
||||
</div>
|
||||
<div id="generalInstructions">
|
||||
|
||||
<h2>Edit our site in the cloud</h2>
|
||||
|
||||
<p>Click the below button to visit the repo for our site. You can then click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it.</p>
|
||||
|
||||
<p><a class="button" href="https://github.com/kubernetes/kubernetes.github.io/">Browse this site's source code</a></p>
|
||||
|
||||
</div>
|
||||
<!-- END: Dynamic section -->
|
||||
|
||||
## Staging your changes in the cloud
|
||||
|
||||
If you want to see your changes staged without having to install anything locally,
|
||||
change your fork of our repo to be named:
|
||||
|
||||
YOUR_GITHUB_USERNAME.github.io
|
||||
|
||||
Then, visit: [http://YOUR_GITHUB_USERNAME.github.io](http://YOUR_GITHUB_USERNAME.github.io)
|
||||
|
||||
You should see a special-to-you version of the site.
|
||||
|
||||
## Editing and staging the site locally
|
||||
|
||||
If you want to work offline, run the below commands to setup
|
||||
your environment for running GitHub pages locally. Then, any edits you make will be viewable
|
||||
on a lightweight webserver that runs on your local machine.
|
||||
|
||||
First install rvm
|
||||
|
||||
```text
|
||||
\curl -sSL https://get.rvm.io | bash -s stable
|
||||
```
|
||||
|
||||
Then load it into your environment
|
||||
|
||||
```shell
|
||||
source /Users/(USERNAME)/.rvm/scripts/rvm (or whatever is prompted by the installer)
|
||||
```
|
||||
|
||||
Then install Ruby 2.2 or higher
|
||||
|
||||
```shell
|
||||
rvm install ruby-2.2.4
|
||||
rvm use ruby-2.2.4 --default
|
||||
```
|
||||
|
||||
Verify that this new version is running (optional)
|
||||
|
||||
```shell
|
||||
which ruby
|
||||
ruby -v
|
||||
```
|
||||
|
||||
Install the GitHub Pages package, which includes Jekyll:
|
||||
|
||||
```shell
|
||||
gem install github-pages
|
||||
```
|
||||
|
||||
Clone our site
|
||||
|
||||
```shell
|
||||
git clone https://github.com/kubernetes/kubernetes.github.io.git
|
||||
```
|
||||
|
||||
Then, to see it run locally:
|
||||
|
||||
```shell
|
||||
cd kubernetes.github.io
|
||||
jekyll serve
|
||||
```
|
||||
|
||||
Your copy of the site will then be viewable at: [http://0.0.0.0:4000](http://0.0.0.0:4000)
|
||||
(or wherever Ruby tells you).
|
||||
|
||||
If you're a bit rusty with git/GitHub, you might wanna read
|
||||
[this](http://readwrite.com/2013/10/02/github-for-beginners-part-2) for a refresher.
|
||||
|
||||
The above instructions work on Mac and Linux.
|
||||
Windows users, follow [these instructions](https://martinbuberl.com/blog/setup-jekyll-on-windows-and-host-it-on-github-pages/).
|
||||
|
||||
## Thank you!
|
||||
|
||||
Kubernetes thrives on community participation and we really appreciate your
|
||||
contributions to our site and our documentation!
|
||||
|
|
@ -106,7 +106,7 @@ h2, h3, h4 {
|
|||
<div class="col2nd">
|
||||
<h3>Contribute to Our Docs</h3>
|
||||
<p>The docs for Kubernetes are open-source, just like the code for Kubernetes itself. The docs are on GitHub Pages, so you can fork it and it will auto-stage on username.github.io, previewing your changes!</p>
|
||||
<a href="/docs/editdocs/" class="button">Write Docs for K8s</a>
|
||||
<a href="/editdocs/" class="button">Write Docs for K8s</a>
|
||||
</div>
|
||||
<div class="col2nd">
|
||||
<h3>Need Help?</h3>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
layout: docwithnav
|
||||
---
|
||||
|
||||
<!-- BEGIN: Gotta keep this section JS/HTML because it swaps out content dynamically -->
|
||||
<p> </p>
|
||||
<script language="JavaScript">
|
||||
var forwarding=window.location.hash.replace("#","");
|
||||
$( document ).ready(function() {
|
||||
if(forwarding) {
|
||||
$("#generalInstructions").hide();
|
||||
$("#continueEdit").show();
|
||||
$("#continueEditButton").text("Edit " + forwarding);
|
||||
$("#continueEditButton").attr("href", "https://github.com/kubernetes/kubernetes.github.io/edit/master/" + forwarding)
|
||||
} else {
|
||||
$("#generalInstructions").show();
|
||||
$("#continueEdit").hide();
|
||||
}
|
||||
});
|
||||
</script>
|
||||
<div id="continueEdit">
|
||||
|
||||
<h2>Continue your edit</h2>
|
||||
|
||||
<p>Click the below link to edit the page you were just on. When you are done, press "Commit Changes" at the bottom of the screen. This will create a copy of our site on your GitHub account called a "fork." You can make other changes in your fork after it is created, if you want. When you are ready to send us all your changes, go to the index page for your fork and click "New Pull Request" to let us know about it.</p>
|
||||
|
||||
<p><a id="continueEditButton" class="button"></a></p>
|
||||
|
||||
</div>
|
||||
<div id="generalInstructions">
|
||||
|
||||
<h2>Edit our site in the cloud</h2>
|
||||
|
||||
<p>Click the below button to visit the repo for our site. You can then click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it.</p>
|
||||
|
||||
<p><a class="button" href="https://github.com/kubernetes/kubernetes.github.io/">Browse this site's source code</a></p>
|
||||
|
||||
</div>
|
||||
<!-- END: Dynamic section -->
|
||||
|
||||
|
||||
{% include_relative README.md %}
|
||||
Loading…
Reference in New Issue