Skip to content

Fixed typo in README #3791

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.

Sign up for GitHub

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

Open
akanksha106-code wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Fixed typo in README #3791

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 68 additions & 137 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,216 +1,147 @@
[中文](./README_CN.md) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/jenkins-x/jx-docs)
# Jenkins X Documentation

# Jenkins X Docs
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/jenkins-x/jx-docs)
[中文文档](./README_CN.md)

<a id="markdown-jenkins-x-docs" name="jenkins-x-docs"></a>
This repository contains the source files for [jenkins-x.io](http://jenkins-x.io/). For the best experience, please read the documentation at [jenkins-x.io](http://jenkins-x.io/) as some links may not work when viewing directly in this repository.

This repository contains the source files for [jenkins-x.io](http://jenkins-x.io/)

**NOTE:** Please browse these docs on [jenkins-x.io](http://jenkins-x.io/). Not all links work when browsing the Markdown files inside this repository.

---

<!-- TOC -->

- [Building the docs](#building-the-docs)
- [Preparing the sources](#preparing-the-sources)
- [Git submodules](#git-submodules)
- [Downloading npm modules](#downloading-npm-modules)
- [Running Hugo](#running-hugo)
- [Locally](#locally)
- [Dockerized](#dockerized)
- [Common Workflows](#common-workflows)
- [Running spell check](#running-spell-check)
- [Checking links, images, etc](#checking-links-images-etc)
- [Adding redirects](#adding-redirects)
- [Upgrading the enhancements content](#upgrading-the-enhancements-content)
- [Localization](#localization)
## Table of Contents
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Building the Documentation](#building-the-documentation)
- [Development Tools](#development-tools)
- [Content Management](#content-management)
- [Contributing](#contributing)

<!-- /TOC -->

---

## Building the docs
## Prerequisites

<a id="markdown-building-the-docs" name="building-the-docs"></a>
- Git
- Node.js and npm
- Hugo (see [Makefile](./Makefile) for recommended version)
- Docker (optional, for containerized development)

### Preparing the sources

<a id="markdown-preparing-the-sources" name="preparing-the-sources"></a>

To edit the docs locally, you need to clone this repository:
## Getting Started

1. Clone the repository with submodules:
```bash
git clone --recurse-submodules --depth 1 https://github.com/jenkins-x/jx-docs.git
git clone --recurse-submodules --depth 1 https://github.com/jenkins-x/jx-docs.git
cd jx-docs
```

#### Git submodules
2. Install dependencies:
```bash
npm install
```

<a id="markdown-git-submodules" name="git-submodules"></a>
## Development Setup

Notice the use of `--recurse-submodules` in the clone command above.
This option will pull in two git [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), namely
[docsy](https://github.com/google/docsy) and [labs-enhancements](https://github.com/jenkins-x/enhancements).
### Git Submodules Management

If you already have a git clone without the submodules checked out you can run:
This repository uses two submodules:
- [docsy](https://github.com/google/docsy) - Documentation theme
- [labs-enhancements](https://github.com/jenkins-x/enhancements) - Jenkins X enhancements

Common submodule operations:
```bash
# Update submodules after fresh clone
git submodule update --init --recursive
```

In subsequent updates of the sources via `git pull` also remember to pull the changes from the submodules:

```bash
# Update submodules with latest changes
git pull --recurse-submodules
```

you can view the commit sha of the sub-modules via:

```bash
# Check submodule status
git submodule status --recursive
```

### Downloading npm modules

<a id="markdown-downloading-npm-modules" name="downloading-npm-modules"></a>
## Building the Documentation

After getting all the sources, you need to [install npm](https://www.npmjs.com/get-npm) and make sure the required npm modules are installed:
### Local Development

1. Set required environment variable:
```bash
npm install
set HUGO_GH_ACCESS_TOKEN=<your_github_token>
```

### Running Hugo

<a id="markdown-running-hugo" name="running-hugo"></a>

The site itself is built with [Hugo](https://gohugo.io/) and configured in [`config.toml`](./config.toml).
You have two options to run Hugo, either directly on your machine or via [Docker Compose](https://github.com/docker/compose).
The following two sections describe the two alternatives in more detail.

**NOTE:** Hugo renders the site in memory in development mode.
Per default, no content is written to disk.

#### Locally

<a id="markdown-locally" name="locally"></a>

If you want to build the site locally on your machine, you need to [install](https://gohugo.io/getting-started/installing) Hugo.
Check the [Makefile](./Makfile) for the latest recommended version use and check whether the environment variables of Golang are set.
Set the env variable HUGO_GH_ACCESS_TOKEN to a github token that can read from jenkins-x/jx repo to allow the contributors plugin to run.

Once installed, you can run:

2. Start Hugo server:
```bash
make server
```
Access the site at [http://localhost:1313](http://localhost:1313)

You can now access the site under [localhost:1313](http://localhost:1313).

#### Dockerized

<a id="markdown-dockerized" name="dockerized"></a>

Instead of installing Hugo locally, you can use the provided `docker-compose.yml` to spin up the Hugo server in a containerized environment.
Make sure you have [Docker](https://docs.docker.com/install/) installed.
### Docker Development

1. Start the containerized environment:
```bash
make compose-up
```

You can now access the site under [localhost:1313](http://localhost:1313).
The Hugo server is running in the background.
You can stop it via:

2. Stop the environment:
```bash
make compose-down
```
Access the site at [http://localhost:1313](http://localhost:1313)

## Common Workflows

<a id="markdown-common-workflows" name="common-workflows"></a>

### Running spell check
## Development Tools

<a id="markdown-running-spell-check" name="running-spell-check"></a>

We are not all masters of spelling, so luckily there are tools to help us fix that.
We are using [node-markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) to run through all our markdown files and list any spelling issue or unknown word.

To make this as simple as possible, just run the following command:
### Spell Checker

Run spell check on markdown files:
```bash
make spellcheck
```
Add new valid words to [.spelling](./.spelling) file (maintain alphabetical order).

The report likely includes words that are spelt correctly, but that just means the spell checker is not aware of the correct spelling (happens a lot for technical terms, commands, etc.).
Please edit [`.spelling`](./.spelling) and add the unknown word.
Also, please try and keep the list alphabetically sorted, which makes it easier to navigate.

### Checking links, images, etc

<a id="markdown-checking-links-images-etc" name="checking-links-images-etc"></a>

To get help in checking all the links, we'll use [htmlproofer](https://github.com/chabad360/htmlproofer).
### Link Checker

Verify all links and images:
```bash
make linkcheck
```
> Note: Initial run may be slow due to external link validation.

**NOTE:** The initial run is really slow (due to external link checks) and that the cache is only build up when it finishes.

**NOTE:**: It's safe to ignore the `... x509: certificate ...` errors for now
## Content Management

### Adding redirects

<a id="markdown-adding-redirects" name="adding-redirects"></a>

If you move a page to a different location you can add a redirect via using an _aliases_ entry in the header of the page:
### Page Redirects

Add redirects for moved content using YAML front matter:
```yaml
aliases:
- /some/old/path
- /another/path
- /previous/path
- /old/path
```

### Upgrading the enhancements content

<a id="markdown-upgrading-the-enhancements-content" name="upgrading-the-enhancements-content"></a>

To upgrade to a new enhancements commit - we'll hopefully automate this soon!
### Updating Content

#### Upgrade Enhancements
```bash
cd content/en/docs/labs/enhancements
git checkout master
git pull
cd ..
git add enhancements
git commit -m "move to latest enhancements"
git commit -m "chore: update enhancements content"
```

### Upgrading docsy

Docsy is added to the jx-docs repository as a submodule under the themes directory.
To update docsy, run the following commands:

#### Upgrade Docsy Theme
```bash
cd themes/docsy
git pull origin master
git submodule update --init --recursive
```

## Localization
### Localization

<a id="markdown-localization" name="localization"></a>
We welcome contributions in different languages. Please see language-specific guides:
- [Chinese Documentation Guide](Localization_Chinese.md)

To let more people know Jenkins X better, localization is essential and meaningful.
And we should keep some rules about this, please read related languages below:
## Contributing

- [Chinese](Localization_Chinese.md)
For detailed contribution guidelines, please refer to our [Documentation Contributing Guide](https://jenkins-x.io/community/documentation/).

## Contributing
---

<a id="markdown-contributing" name="contributing"></a>
## Support

Please refer to the documentation contributing guide available at [Jenkins X website](https://jenkins-x.io/community/documentation/).
- [Jenkins X Website](https://jenkins-x.io)
- [Community](https://jenkins-x.io/community/)