diff --git a/build.sh b/build.sh index 486abca..3216579 100755 --- a/build.sh +++ b/build.sh @@ -1,5 +1,7 @@ #!/usr/bin/env sh +[ ! -d "node_modules" ] && npm ci + ./node_modules/cspell/bin.js "docs/**/*.md" mkdocs build linkchecker -f linkcheckerrc public diff --git a/devfile.yaml b/devfile.yaml new file mode 100644 index 0000000..ad1394e --- /dev/null +++ b/devfile.yaml @@ -0,0 +1,38 @@ +apiVersion: 1.0.0 +metadata: + name: okd-io +components: + - id: vscode/typescript-language-features/latest + type: chePlugin + - id: ms-vscode/node-debug2/latest + type: chePlugin + - id: redhat/vscode-openshift-connector/latest + type: chePlugin + - mountSources: true + endpoints: + - name: MkDocs + port: 8000 + command: + - sleep + - infinity + memoryLimit: 512Mi + type: dockerimage + alias: okd-io + image: 'quay.io/brianinnesuk/mkdocs-builder:1.0.1' + - id: redhat/vscode-yaml/latest + type: chePlugin + - id: redhat/vscode-xml/latest + type: chePlugin +commands: + - name: 1. Live edit + actions: + - workdir: '${CHE_PROJECTS_ROOT}/okd.io' + type: exec + command: 'mkdocs serve -a 0.0.0.0:8000' + component: okd-io + - name: 2. Build + actions: + - workdir: '${CHE_PROJECTS_ROOT}/okd.io' + type: exec + command: ./build.sh + component: okd-io \ No newline at end of file diff --git a/docs/wg_docs/content.md b/docs/wg_docs/content.md new file mode 100644 index 0000000..5dd561e --- /dev/null +++ b/docs/wg_docs/content.md @@ -0,0 +1,312 @@ +## Site content maintainability + + + +The site has adopted Markdown as the standard way to create content for the site. Previously the site used an HTML based framework, which resulted in content not being frequently updated as there was a steep learning curve. + +All content on the site should be created using Markdown. To ensure content is maintainable going forward only markdown features outlined below should be used to create site content. If you wish to use additional components on a page then please contact the documentation working group to discuss your requirements before creating a pull request containing additional components. + +MkDocs includes the ability to create custom page templates. This facility has been used to create a customized home page for the site. If any other pages require a custom layout or custom features, then a page template should be used so the content can remain in Markdown. Creation of custom page templates should be discussed with the documentation working group. + +## Changing content + +MkDocs supports standard Markdown syntax and a set Markdown extensions provided by plugins. The exact Markdown syntax supported is based on the [python implementation](https://python-markdown.github.io). + +MkDocs is configured using the **mkdocs.yml** file in the root of the git repository. + +The **mkdoc.yml** file defines the top level navigation for the site. The level of indentation is configurable (this requires the theme to support this feature) with Markdown headings, levels 2 (`##`) and 3 (`###`) being used for the in-page navigation on the right of the page. + +### Standard Markdown features + +The following markdown syntax is used within the documentation + +| Syntax | Result +|--------|----------- +|`# Title` | heading - you can create up to 6 levels of headings by adding additional `#` characters, so `###` is a level 3 heading +|`**text**` | will display the word ```text``` in **bold** +|`*text*` | will display the word ```text``` in *italic* +| `` `code` `` | inline code block +| ```` ```shell ... ``` ````| multi-line (Fenced) code block +| `1. list item` | ordered list +| `- unordered list item` | unordered list +| `---` | horizontal break + +HTML can be embedded in Markdown, but embedded HTML should not be used in the documentation. All content should use Markdown with the permitted extensions. + +### Indentation + +MkDocs uses 4 spaces for tabs, so when indenting code ensure you are working with tabs set to 4 spaces rather than 2, which is commonly used. + +When using some features of Markdown indentation is used to identify blocks. + +```md +1. Ubiquity EdgeRouter ER-X + - runs DHCP (embedded), custom DNS server via AdGuard + + ![pic](./img/erx.jpg){width=80%} +``` + +In the code block above you will see the unordered list item is indented, so it aligns with the content of the ordered list (rather than aligning with the number of the ordered list). The image is also indented so it too aligns with the ordered list text. + +Many of the Markdown elements can be nested and indentation is used to define the nesting relationship. If you look down on this page at the [Information boxes](#information-boxes) section, the example shows an example of nesting elements and the Markdown tab shows how indentation is being used to identify the nesting relationships. + +### Links within MkDocs generated content + +MkDocs will warn of any internal broken links, so it is important that links within the documentation are recognized as internal links. + +- a link starting with a protocol name, such as http or https, is an external link +- a link starting with `/` is an external link. This is because MkDocs generated content can be embedded into another web application, so links can point outside of the MkDocs generated site but hosted on the same website +- a link starting with a file name (including the .md extension) or relative directory (../directory/filename.md) is an internal link and will be verified by MkDocs + +!!!Information + Internal links should be to the Markdown file (with .md extension). When the site is generated the filename will be automatically converted to the correct URL + +As part of the build process a linkchecker application will check the generated html site for any broken links. You can run this linkchecker locally using the instructions. If any links in the documentation should be excluded from the link checker, such as links to localhost, then they should be added as a regex to the linkcheckerrc file, located in the root folder of the project - see [linkchecker documentation](https://linkchecker.github.io/linkchecker/index.html) for additional information + +## Markdown Extensions used in OKD.io + +There are a number of Markdown extensions being used to create the site. See the mkdocs.yml file to see which extensions are configured. The documentation for the extensions can be found [here](https://python-markdown.github.io/extensions/) + +### Link configuration + +Links on the page or embedded images can be annotated to control the links and also the appearance of the links: + +#### Image + +Images are embedded in a page using the standard Markdown syntax `![description](URL)`, but the image can be formatted with [Attribute Lists](https://python-markdown.github.io/extensions/attr_list/){: target="_blank" .external }. This is most commonly used to scale an image or center an image, e.g. + +```md +![GitHub repo url](images/github-repo-url.png){style="width: 80%" .center } +``` + +#### External Links + +External links can also use attribute lists to control behaviors, such as open in new tab or add a css class attribute to the generated HTML, such as **external** in the example below: + +```md +[MkDocs](http://mkdocs.org){: target="_blank" .external } +``` + +!!!info + You can embed an image as the description of a link to create clickable images that launch to another site: `[![Image description](Image URL)](target URL "hover text"){: target=_blank}` + +#### YouTube videos + +It is not possible to embed a YouTube video and have it play in place using pure markdown. You can use HTML within the markdown file to embed a video: + +```html + +``` + +### Tabs + +Content can be organized into a set of horizontal tabs. + +```md +=== "Tab 1" + Hello + +=== "Tab 2" + World +``` + +produces : + +=== "Tab 1" + Hello + +=== "Tab 2" + World + +### Information boxes + +The [Admonition](https://python-markdown.github.io/extensions/admonition/){: target="_blank" .external } extension allows you to add themed information boxes using the `!!!` and `???` syntax: + +```md +!!! note + This is a note +``` + +produces: + +!!! note + This is a note + +and + +```text +??? note + This is a collapsible note + + You can add a `+` character to force the box to be initially open `???+` +``` + +produces a collapsible box: + +??? note + This is a collapsible note + + You can add a `+` character to force the box to be initially open `???+` + +You can override the title of the box by providing a title after the Admonition type. + +!!!Example + You can also nest different components as required + + === "note" + !!!note + This is a note + + === "collapsible note" + ???+note + This is a note + + === "custom title note" + !!!note "Sample Title" + This is a note + + === "Markdown" + ```md + !!!Example + You can also nest different components as required + + === "note" + !!!note + This is a note + + === "collapsible note" + ???+note + This is a note + + === "custom title note" + !!!note "Sample Title" + This is a note + ``` + +#### Supported Admonition Classes + +The Admonitions supported by the Material theme are : + +!!! note + This is a note + +!!! abstract + This is an abstract + +!!! info + This is an info + +!!! tip + This is a tip + +!!! success + This is a success + +!!! question + This is a question + +!!! warning + This is a warning + +!!! failure + This is a failure + +!!! danger + This is a danger + +!!! bug + This is a bug + +!!! example + This is an example + +!!! quote + This is a quote + +### Code blocks + +Code blocks allow you to insert code or blocks of text in line or as a block. + +To use inline you simply enclose the text using a single back quote **\`** character. So a command can be included using **\`oc get pods\`** and will create `oc get pods` + +When you want to include a block of code you use a *fence*, which is 3 back quote character at the start and end of the block. After the opening quotes you should also specify the content type contained in the block. + +````text +```shell +oc get pods +``` +```` + +which will produce: + +``` shell +oc get pods +``` + +Notice that the block automatically gets the *copy to clipboard* link to allow easy copy and paste. + +Every code block needs to identify the content. Where there is no content type, then **text** should be used to identify the content as plain text. Some of the common content types are shown in the table below. However, a full link of supported content types can be found [here](https://pygments.org/docs/lexers/){: target="_blank"}, where the short name in the documentation should be used. + +| type | Content +|------|-------- +| **shell** | Shell script content +| **powershell** | Windows Power Shell content +| **bat** | Windows batch file (.bat or .cmd files) +| **json** | JSON content +| **yaml** | YAML content +| **markdown** or **md** | Markdown content +| **java** | Java programming language +| **javascript** or **js** | JavaScript programming language +| **typescript** or **ts** | TypeScript programming language +| **text** | Plain text content + +#### Advanced highlighting of code blocks + +There are some additional features available due to the highlight plugin installed in MkDocs. Full details can be found in the [MkDocs Materials documentation](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/){: target=_blank}. + +#### Line numbers + +You can add line numbers to a code block with the **linenums** directive. You must specify the starting line number, 1 in the example below: + +```` md +``` javascript linenums="1" + +``` +```` + +creates + +``` javascript linenums="1" + +``` + +!!!Info + The line numbers do not get included when the copy to clipboard link is selected + +## Spell checking + +This project uses [cSpell](https://github.com/streetsidesoftware/cspell){: target=_blank} to check spelling within the markdown. The configuration included in the project automatically excludes content in a code block, enclosed in triple back quotes \`\`\`. + +The configuration file also specifies that US English is the language used in the documentation, so only US English spellings should be used for words where alternate international English spellings exist. + +You can add words to be considered valid either within a markdown document or within the cspell configuration file, **cspell.json**, in the root folder of the documentation repository. + +Words defined within a page only apply to that page, but words added to the configuration file apply to the entire project. + +### Adding local words + +You can add a list of words to be considered valid for spell checking purposes as a comment in a Markdown file. + +The comment has a specific format to be picked up by the cSpell tool: + +`````` + +here the words *linkchecker*, *linkcheckerrc*, *mkdocs* and *mkdoc* are specified as words to be accepted by the spell checker within the file containing the comment. + +### Adding global words + +The cSpell configuration file **cspell.json** contains a list of words that should always be considered valid when spell checking. The list of words applies to all files being checked. \ No newline at end of file diff --git a/docs/wg_docs/doc-env.md b/docs/wg_docs/doc-env.md new file mode 100644 index 0000000..d2a6eae --- /dev/null +++ b/docs/wg_docs/doc-env.md @@ -0,0 +1,269 @@ +## Setting up a documentation environment + + + +To work on documentation and be able to view the rendered web site you need to create an environment, which comprises of: + +- [MkDocs](https://www.mkdocs.org){: target=_blank} with the [Materials theme](https://squidfunk.github.io/mkdocs-material/){: target=_blank} +- [CSpell](https://cspell.org/){: target=_blank} +- [linkchecker](https://linkchecker.github.io/linkchecker/){: target=_blank} +- [Node.js](https://nodejs.org/en/){: target=_blank} +- [Python 3](https://www.python.org){: target=_blank} + +You can create the environment by : + +- running the tooling within a container runtime, so you don't need to do any local installs +- if you have an Eclipse Che installation on an OKD cluster then you can make the changes using only a browser, with all the tooling running inside Che on the OKD cluster. +- installing the components on your local system + +=== "Tooling within a container" + + You can use a container to run MkDocs so no local installation is required, however you do need to have [Docker Desktop](https://www.docker.com/products/docker-desktop){: target=_blank} installed if using Mac OS or Windows. If running on Linux you can use **Docker** or **Podman**. + + *If you have a node.js environment installed that includes the npm command then you can make use of the run scripts provided in the project to run the docker or podman commands* + + The following commands all assume you are working in the root directory of your local git clone of your forked copy of the okd.io git repo. *(your working directory should contain mkdocs.yml and package.json files)* + + !!!Warning + If you are using Linux with SELinux enabled, then you need to configure your system to allow the local directory containing the cloned git repo to be mounted inside a container. The following commands will configure SELinux to allow this: + + (change the path to the location of your okd.io directory) + + ```shell + sudo semanage fcontext -a -t container_file_t '/home/brian/Documents/projects/okd.io(/.*)?' + sudo restorecon -Rv /home/brian/Documents/projects/okd.io + ``` + + ### Creating the container + + To create the container image on your local system choose the appropriate command from the list: + + - if you are using the docker command on Linux, Mac OS or Windows: + + ```shell + docker build -t mkdocs-build -f ./dev/Dockerfile . + ``` + + - if you are using the podman command on Linux: + + ```shell + podman build -t mkdocs-build -f ./dev/Dockerfile . + ``` + + - if you have npm and use Docker on Linux, Mac OS or Windows: + + ```shell + npm run docker-build-image + ``` + + - if you have npm and use Podman on Linux: + + ```shell + npm run podman-build-image + ``` + + This will build a local container image named mkdocs-build + + ### Live editing of the content + + To change the content of the web site you can use your preferred editing application. To see the changes you can run a live local copy of **okd.io** that will automatically update as you save local changes. + + Ensure you have the local container image, built in the previous step, available on your system then choose the appropriate command from the list: + + - if you are using the docker command on Linux or Mac OS: + + ```shell + docker run -it --rm --name mkdocs-serve -p 8000:8000 -v `pwd`:/site mkdocs-build + ``` + + - if you are using the podman command on Linux: + + ```shell + podman run -it --rm --name mkdocs-serve -p 8000:8000 -v `pwd`:/site mkdocs-build + ``` + + - if you are on Windows using the docker command in Powershell: + + ```powershell + docker run -it --rm --name mkdocs-build -p 8000:8000 -v "$(pwd):/site" mkdocs-build + ``` + + - if you are on Windows using the docker command in CMD prompt: + + ```cmd + docker run -it --rm --name mkdocs-build -p 8000:8000 -v %cd%:/site mkdocs-build + ``` + + - if you have npm and use Docker on Linux or Mac OS: + + ```shell + npm run docker-serve + ``` + + - if you have npm on Windows: + + ```shell + npm run win-docker-serve + ``` + + - if you have npm and use Podman on Linux: + + ```shell + npm run podman-serve + ``` + + You can now open a browser to [localhost:8000](http://localhost:8000){: target=_blank}. You should see the **okd.io** web site in the browser. As you change files on your local system the web pages will automatically update. + + When you have completed editing the site use *Ctrl-c* (hold down the control key then press c) to quit the site. + + ### Build and validate the site + + Before you submit any changes to the site in a pull request please check there are no [spelling mistakes](./okd-io.md#spell-checking) or [broken links](./okd-io.md#links-within-mkdocs-generated-content), by running the build script and checking the output. + + The build script will create or update the static web site in the **public** directory - this is what will be created and published as the live site if you submit a pull request with your modifications. + + - if you are using the docker command on Linux or Mac OS: + + ```shell + docker run -it --rm --name mkdocs-build -p -v `pwd`:/site --entrypoint /site/build.sh mkdocs-build + ``` + + - if you are using the podman command on Linux: + + ```shell + podman run -it --rm --name mkdocs-build -p -v `pwd`:/site --entrypoint /site/build.sh mkdocs-build + ``` + + - if you are on Windows using the docker command in Powershell: + + ```powershell + docker run -it --rm --name mkdocs-build -v "$(pwd):/site" --entrypoint /site/build.sh mkdocs-build + ``` + + - if you are on Windows using the docker command in CMD prompt: + + ```cmd + docker run -it --rm --name mkdocs-build -v %cd%:/site --entrypoint /site/build.sh mkdocs-build + ``` + + - if you have npm and use Docker on Linux or Mac OS: + + ```shell + npm run docker-build + ``` + + - if you have npm on Windows: + + ```shell + npm run win-docker-build + ``` + + - if you have npm and use Podman on Linux: + + ```shell + npm run podman-build + ``` + + You should verify there are no spelling mistakes, by finding the last line of the CSpell output: + + ```text + CSpell: Files checked: 31, Issues found: 0 in 0 files + ``` + + Further down in the console output wil be the summary of the link checker: + + ```text + That's it. 662 links in 695 URLs checked. 0 warnings found. 0 errors found + ``` + + Any issues reported should be fixed before submitting a pull request to add your changes to the okd.io site. + +=== "Editing on cluster" + + There is a community operator available in the OperatorHub on OKD to install Eclipse Che, the upstream project for Red Hat CodeReady Workspaces. + + You can use Che to modify site content through your browser, with your OKD cluster hosting the workspace and developer environment. + + You need to have access to an OKD cluster and have the Che operator installed and an Che instance deployed and running. + + In your OKD console, you should have an applications link in the top toolbar. Open the Applications menu (3x3 grid icon) and select Che. This will open the Che application - Google Chrome is the supported browser and will give the best user experience. + + In the Che console side menu, select to **Create Workspace**, then in the **Import from Git** section add the URL of *your* fork of the okd.io git repository (should be similar to `https://github.com//okd.io.git`) then press **Create & Open** to start the workspace. + + After a short while the workspace will open (*the cluster has to download and start a number of containers, so the first run may take a few minutes depending on your cluster network access*). When the workspace is displayed you may have to wait a few seconds for the workspace to initialize and clone your git repo into the workspace. You may also get asked if you trust the author of the git repository, answer yes to this question. Your environment should then be ready to start work. + + The web based developer environment uses the same code base as Microsoft Visual Studio Code, so provides a similar user experience, but within your browser. + + ### Live editing of the content + + To change the content of the web site you can use the in browser editor provided by Che. To see the changes you can run a live local copy of **okd.io** that will automatically update as you save local changes. + + On the right side of the workspace window you should see 3 icons, hovering over them should reveal they are the **Outline**, **Endpoints** and **Workspace**. Clicking into the workspace, you should see a **User Runtimes** section with the option to open a new terminal, then 2 commands (Live edit and Build) and finally a link to launch MkDocs web site (initially this link will not work) + + To allow you to see your changes in a live site (where any change you save will automatically be updated on the site) click on the **1. Live edit** link. This will launch a new terminal window where the **mkdocs serve** command will run, which provides a local live site. However, as you are running the development site on a cluster, the Che runtime automatically makes this site available to you. The **MkDocs** link now points to the site, but you will be asked if you want to open the site in a new tab or in Preview. + + Preview will add a 4th icon to the side toolbar and open the web site in the side panel. You can drag the side of the window to resize the browser view to allow you to edit on the left and view the results on the right of your browser window. + + If you have multiple monitors you may want to select to open the website in a new Tab or use the **MkDocs** link, then drag the browser tab on to a different monitor. + + By default, the Che environment auto-saves any file modification after half a second of no activity. You can alter this in the preferences section. When ever a file is saved the live site will update in the browser. + + When you finished editing simply close the terminal window running the Live edit script. This will stop the web server running the preview site. + + ### Build and validate the site + + + The build script will create or update the static web site in the **public** directory - this is what will be created and published as the live site if you submit a pull request with your modifications. + + To run the build script simply click the **2. Build** link in the Workspace panel. + + You should verify there are no spelling mistakes, by finding the last line of the CSpell output: + + ```text + CSpell: Files checked: 31, Issues found: 0 in 0 files + ``` + + Further down in the console output wil be the summary of the link checker: + + ```text + That's it. 662 links in 695 URLs checked. 0 warnings found. 0 errors found + ``` + + Any issues reported should be fixed before submitting a pull request to add your changes to the okd.io site. + +=== "Local mkdocs and python tooling installation" + + You can install MkDocs and associated plugins on your development system and run the tools locally: + + - Install [Python 3](https://www.python.org){: target=_blank} on your system + - Install [Node.js](https://nodejs.org/en/){: target=_blank} on your system + - Clone **your fork** of the [okd.io repository](https://github.com/openshift-cs/okd.io/){: target=_blank} + - cd into the local repo directory (./okd.io) + - Install the required python packages `pip install -r requirements.txt' + - Install the spell checker using command `npm ci`. If you want to use the cspell command on the command line, then you need to install it globally `npm -g i cspell` + + !!!note + sudo command may be needed to install globally, depending on your system configuration + + You now have all the tools installed to be able to create the static HTML site from the markdown documents. The [documentation for MkDocs](https://www.mkdocs.org){: target=_blank} provides full instructions for using MkDocs, but the important commands are: + + - `mkdocs build` will build the static site. This must be run in the root directory of the repo, where mkdocs.yml is located. The static site will be created/updated in the **public** directory + - `mkdocs serve` will build the static site and launch a test server on `http://localhost:8000`. Every time a document is modified the website will automatically be updated and any browser open will be refreshed to the latest. + - To check links in the built site (`mkdocs build` must be run first), use the linkchecker, with command `linkchecker -f linkcheckerrc --check-extern public`. This command should be run in the root folder of the project, containing the **linkcheckerrc** file. + - To check spelling `cspell docs/**/*.md` should be run in the root folder of the project, containing the **cspell.json** file. + + There is also a convenience script `./build.sh` in the root of the repository that will check spelling, build the site then run the link checker. + + You should verify there are no spelling mistakes, by finding the last line of the CSpell output: + + ```text + CSpell: Files checked: 31, Issues found: 0 in 0 files + ``` + + Similarly, the link checker creates a summary after checking the site: + + ```text + That's it. 662 links in 695 URLs checked. 0 warnings found. 0 errors found + ``` + + Any issues reported should be fixed before submitting a pull request to add your changes to the okd.io site. \ No newline at end of file diff --git a/docs/wg_docs/okd-io.md b/docs/wg_docs/okd-io.md index d718627..68d7965 100644 --- a/docs/wg_docs/okd-io.md +++ b/docs/wg_docs/okd-io.md @@ -1,512 +1,20 @@ # Contributing to okd.io - +The source for **okd.io** is in a [github repository](https://github.com/openshift-cs/okd.io/){: target=_blank}. -The source for **okd.io** is in a [github repository](https://github.com/openshift-cs/okd.io/){: target=_blank}. To update or add new content to the site you need to fork the repository in your own github account, make the changes in your local repository then create a pull request to deliver the updates to the primary repository. +The site is created using [MkDocs](https://www.mkdocs.org){: target=_blank}. which takes Markdown documents and turns them into a static website that can be accessed from a filesystem or served from a web server. -!!!Todo - Add more specific instructions to help those less familiar with git +To update or add new content to the site you need to -## Setting up a documentation environment - -To work on documentation and be able to view the rendered web site you need to create an environment, which comprises of: - -- [MkDocs](https://www.mkdocs.org){: target=_blank} with the [Materials theme](https://squidfunk.github.io/mkdocs-material/){: target=_blank} -- [CSpell](https://cspell.org/){: target=_blank} -- [linkchecker](https://linkchecker.github.io/linkchecker/){: target=_blank} -- [Node.js](https://nodejs.org/en/){: target=_blank} -- [Python 3](https://www.python.org){: target=_blank} - -You can create the environment by installing the components on your local system, alternatively you can run the tooling within a container runtime, so you don't need to do any local installs. - -=== "Tooling within a container" - - You can use a container to run MkDocs so no local installation is required, however you do need to have [Docker Desktop](https://www.docker.com/products/docker-desktop){: target=_blank} installed if using Mac OS or Windows. If running on Linux you can use **Docker** or **Podman**. - - *If you have a node.js environment installed that includes the npm command then you can make use of the run scripts provided in the project to run the docker or podman commands* - - The following commands all assume you are working in the root directory of your local git clone of your forked copy of the okd.io git repo. *(your working directory should contain mkdocs.yml and package.json files)* - - !!!Warning - If you are using Linux with SELinux enabled, then you need to configure your system to allow the local directory containing the cloned git repo to be mounted inside a container. The following commands will configure SELinux to allow this: - - (change the path to the location of your okd.io directory) - - ```shell - sudo semanage fcontext -a -t container_file_t '/home/brian/Documents/projects/okd.io(/.*)?' - sudo restorecon -Rv /home/brian/Documents/projects/okd.io - ``` - - ### Creating the container - - To create the container image on your local system choose the appropriate command from the list: - - - if you are using the docker command on Linux, Mac OS or Windows: - - ```shell - docker build -t mkdocs-build -f ./dev/Dockerfile . - ``` - - - if you are using the podman command on Linux: - - ```shell - podman build -t mkdocs-build -f ./dev/Dockerfile . - ``` - - - if you have npm and use Docker on Linux, Mac OS or Windows: - - ```shell - npm run docker-build-image - ``` - - - if you have npm and use Podman on Linux: - - ```shell - npm run podman-build-image - ``` - - This will build a local container image named mkdocs-build - - ### Live editing of the content - - To change the content of the web site you can use your preferred editing application. To see the changes you can run a live local copy of **okd.io** that will automatically update as you save local changes. - - Ensure you have the local container image, built in the previous step, available on your system then choose the appropriate command from the list: - - - if you are using the docker command on Linux or Mac OS: - - ```shell - docker run -it --rm --name mkdocs-serve -p 8000:8000 -v `pwd`:/site mkdocs-build - ``` - - - if you are using the podman command on Linux: - - ```shell - podman run -it --rm --name mkdocs-serve -p 8000:8000 -v `pwd`:/site mkdocs-build - ``` - - - if you are on Windows using the docker command in Powershell: - - ```powershell - docker run -it --rm --name mkdocs-build -p 8000:8000 -v "$(pwd):/site" mkdocs-build - ``` - - - if you are on Windows using the docker command in CMD prompt: - - ```cmd - docker run -it --rm --name mkdocs-build -p 8000:8000 -v %cd%:/site mkdocs-build - ``` - - - if you have npm and use Docker on Linux or Mac OS: - - ```shell - npm run docker-serve - ``` - - - if you have npm on Windows: - - ```shell - npm run win-docker-serve - ``` - - - if you have npm and use Podman on Linux: - - ```shell - npm run podman-serve - ``` - - You can now open a browser to [localhost:8000](http://localhost:8000){: target=_blank}. You should see the **okd.io** web site in the browser. As you change files on your local system the web pages will automatically update. - - When you have completed editing the site use *Ctrl-c* (hold down the control key then press c) to quit the site. - - ### Build and validate the site - - Before you submit any changes to the site in a pull request please check there are no [spelling mistakes](./okd-io.md#spell-checking) or [broken links](./okd-io.md#links-within-mkdocs-generated-content), by running the build script and checking the output. - - The build script will create or update the static web site in the **public** directory - this is what will be created and published as the live site if you submit a pull request with your modifications. - - - if you are using the docker command on Linux or Mac OS: - - ```shell - docker run -it --rm --name mkdocs-build -p -v `pwd`:/site --entrypoint /site/build.sh mkdocs-build - ``` - - - if you are using the podman command on Linux: - - ```shell - podman run -it --rm --name mkdocs-build -p -v `pwd`:/site --entrypoint /site/build.sh mkdocs-build - ``` - - - if you are on Windows using the docker command in Powershell: - - ```powershell - docker run -it --rm --name mkdocs-build -v "$(pwd):/site" --entrypoint /site/build.sh mkdocs-build - ``` - - - if you are on Windows using the docker command in CMD prompt: - - ```cmd - docker run -it --rm --name mkdocs-build -v %cd%:/site --entrypoint /site/build.sh mkdocs-build - ``` - - - if you have npm and use Docker on Linux or Mac OS: - - ```shell - npm run docker-build - ``` - - - if you have npm on Windows: - - ```shell - npm run win-docker-build - ``` - - - if you have npm and use Podman on Linux: - - ```shell - npm run podman-build - ``` - -=== "Local mkdocs and python tooling installation" - - You can install MkDocs and associated plugins on your development system and run the tools locally: - - - Install [Python 3](https://www.python.org){: target=_blank} on your system - - Install [Node.js](https://nodejs.org/en/){: target=_blank} on your system - - Clone **your fork** of the [okd.io repository](https://github.com/openshift-cs/okd.io/){: target=_blank} - - cd into the local repo directory (./okd.io) - - Install the required python packages `pip install -r requirements.txt' - - Install the spell checker using command `npm ci` - - !!!note - sudo command may be needed to install globally, depending on your system configuration - - You now have all the tools installed to be able to create the static HTML site from the markdown documents. The [documentation for MkDocs](https://www.mkdocs.org){: target=_blank} provides full instructions for using MkDocs, but the important commands are: - - - `mkdocs build` will build the static site. This must be run in the root directory of the repo, where mkdocs.yml is located. The static site will be created/updated in the **public** directory - - `mkdocs serve` will build the static site and launch a test server on `http://localhost:8000`. Every time a document is modified the website will automatically be updated and any browser open will be refreshed to the latest. - - To check links in the built site (`mkdocs build` must be run first), use the linkchecker, with command `linkchecker -f linkcheckerrc --check-extern public`. This command should be run in the root folder of the project, containing the **linkcheckerrc** file. - - To check spelling `cspell docs/**/*.md` should be run in the root folder of the project, containing the **cspell.json** file. - - There is also a convenience script `./build.sh` in the root of the repository that will check spelling, build the site then run the link checker. +- fork the repository in your own github account + - it important to leave the repo name as **okd.io** in your github account if you want to use Che/CodeReady Containers to modify the content +- make the changes in your local repository +- create a pull request to deliver the updates to the primary repository. The site is created using [MkDocs](http://mkdocs.org){: target="_blank" .external } with the [Materials theme](https://squidfunk.github.io/mkdocs-material/){: target="_blank" .external } theme. -MkDocs takes Markdown documents and turns them into a static website that can be accessed from a filesystem or served from a web server. - ## Updating the site -To make your changes live, create a pull request to deliver the changes in your fork of the repo to the main branch of the **okd.io** repo. +To make changes to the site. Create a pull request to deliver the changes in your fork of the repo to the main branch of the **okd.io** repo. Before creating a pull request you should run the build script and verify there are no spelling mistakes or broken links. Details on how to do this can be found at the end of the instructions for [setting up a documentation environment](doc-env.md) Github automation is used to generate the site then publish to github pages, which serves the site. If your changes contain spelling issues or broken links, then the automation will fail and the github pages site will not be updated, so please do a local test using the **build.sh** script before creating the pull request. - -## Site content maintainability - -The site has adopted Markdown as the standard way to create content for the site. Previously the site used an HTML based framework, which resulted in content not being frequently updated as there was a steep learning curve. - -All content on the site should be created using Markdown. To ensure content is maintainable going forward only markdown features outlined below should be used to create site content. If you wish to use additional components on a page then please contact the documentation working group to discuss your requirements before creating a pull request containing additional components. - -MkDocs includes the ability to create custom page templates. This facility has been used to create a customized home page for the site. If any other pages require a custom layout or custom features, then a page template should be used so the content can remain in Markdown. Creation of custom page templates should be discussed with the documentation working group. - -## Changing content - -MkDocs supports standard Markdown syntax and a set Markdown extensions provided by plugins. The exact Markdown syntax supported is based on the [python implementation](https://python-markdown.github.io). - -MkDocs is configured using the **mkdocs.yml** file in the root of the git repository. - -The **mkdoc.yml** file defines the top level navigation for the site. The level of indentation is configurable (this requires the theme to support this feature) with Markdown headings, levels 2 (`##`) and 3 (`###`) being used for the in-page navigation on the right of the page. - -### Standard Markdown features - -The following markdown syntax is used within the documentation - -| Syntax | Result -|--------|----------- -|`# Title` | heading - you can create up to 6 levels of headings by adding additional `#` characters, so `###` is a level 3 heading -|`**text**` | will display the word ```text``` in **bold** -|`*text*` | will display the word ```text``` in *italic* -| `` `code` `` | inline code block -| ```` ```shell ... ``` ````| multi-line (Fenced) code block -| `1. list item` | ordered list -| `- unordered list item` | unordered list -| `---` | horizontal break - -HTML can be embedded in Markdown, but embedded HTML should not be used in the documentation. All content should use Markdown with the permitted extensions. - -### Indentation - -MkDocs uses 4 spaces for tabs, so when indenting code ensure you are working with tabs set to 4 spaces rather than 2, which is commonly used. - -When using some features of Markdown indentation is used to identify blocks. - -```md -1. Ubiquity EdgeRouter ER-X - - runs DHCP (embedded), custom DNS server via AdGuard - - ![pic](./img/erx.jpg){width=80%} -``` - -In the code block above you will see the unordered list item is indented, so it aligns with the content of the ordered list (rather than aligning with the number of the ordered list). The image is also indented so it too aligns with the ordered list text. - -Many of the Markdown elements can be nested and indentation is used to define the nesting relationship. If you look down on this page at the [Information boxes](#information-boxes) section, the example shows an example of nesting elements and the Markdown tab shows how indentation is being used to identify the nesting relationships. - -### Links within MkDocs generated content - -MkDocs will warn of any internal broken links, so it is important that links within the documentation are recognized as internal links. - -- a link starting with a protocol name, such as http or https, is an external link -- a link starting with `/` is an external link. This is because MkDocs generated content can be embedded into another web application, so links can point outside of the MkDocs generated site but hosted on the same website -- a link starting with a file name (including the .md extension) or relative directory (../directory/filename.md) is an internal link and will be verified by MkDocs - -!!!Information - Internal links should be to the Markdown file (with .md extension). When the site is generated the filename will be automatically converted to the correct URL - -As part of the build process a linkchecker application will check the generated html site for any broken links. You can run this linkchecker locally using the instructions. If any links in the documentation should be excluded from the link checker, such as links to localhost, then they should be added as a regex to the linkcheckerrc file, located in the root folder of the project - see [linkchecker documentation](https://linkchecker.github.io/linkchecker/index.html) for additional information - -## Markdown Extensions used in OKD.io - -There are a number of Markdown extensions being used to create the site. See the mkdocs.yml file to see which extensions are configured. The documentation for the extensions can be found [here](https://python-markdown.github.io/extensions/) - -### Link configuration - -Links on the page or embedded images can be annotated to control the links and also the appearance of the links: - -#### Image - -Images are embedded in a page using the standard Markdown syntax `![description](URL)`, but the image can be formatted with [Attribute Lists](https://python-markdown.github.io/extensions/attr_list/){: target="_blank" .external }. This is most commonly used to scale an image or center an image, e.g. - -```md -![GitHub repo url](images/github-repo-url.png){style="width: 80%" .center } -``` - -#### External Links - -External links can also use attribute lists to control behaviors, such as open in new tab or add a css class attribute to the generated HTML, such as **external** in the example below: - -```md -[MkDocs](http://mkdocs.org){: target="_blank" .external } -``` - -!!!info - You can embed an image as the description of a link to create clickable images that launch to another site: `[![Image description](Image URL)](target URL "hover text"){: target=_blank}` - -#### YouTube videos - -It is not possible to embed a YouTube video and have it play in place using pure markdown. You can use HTML within the markdown file to embed a video: - -```html - -``` - -### Tabs - -Content can be organized into a set of horizontal tabs. - -```md -=== "Tab 1" - Hello - -=== "Tab 2" - World -``` - -produces : - -=== "Tab 1" - Hello - -=== "Tab 2" - World - -### Information boxes - -The [Admonition](https://python-markdown.github.io/extensions/admonition/){: target="_blank" .external } extension allows you to add themed information boxes using the `!!!` and `???` syntax: - -```md -!!! note - This is a note -``` - -produces: - -!!! note - This is a note - -and - -```text -??? note - This is a collapsible note - - You can add a `+` character to force the box to be initially open `???+` -``` - -produces a collapsible box: - -??? note - This is a collapsible note - - You can add a `+` character to force the box to be initially open `???+` - -You can override the title of the box by providing a title after the Admonition type. - -!!!Example - You can also nest different components as required - - === "note" - !!!note - This is a note - - === "collapsible note" - ???+note - This is a note - - === "custom title note" - !!!note "Sample Title" - This is a note - - === "Markdown" - ```md - !!!Example - You can also nest different components as required - - === "note" - !!!note - This is a note - - === "collapsible note" - ???+note - This is a note - - === "custom title note" - !!!note "Sample Title" - This is a note - ``` - -#### Supported Admonition Classes - -The Admonitions supported by the Material theme are : - -!!! note - This is a note - -!!! abstract - This is an abstract - -!!! info - This is an info - -!!! tip - This is a tip - -!!! success - This is a success - -!!! question - This is a question - -!!! warning - This is a warning - -!!! failure - This is a failure - -!!! danger - This is a danger - -!!! bug - This is a bug - -!!! example - This is an example - -!!! quote - This is a quote - -### Code blocks - -Code blocks allow you to insert code or blocks of text in line or as a block. - -To use inline you simply enclose the text using a single back quote **\`** character. So a command can be included using **\`oc get pods\`** and will create `oc get pods` - -When you want to include a block of code you use a *fence*, which is 3 back quote character at the start and end of the block. After the opening quotes you should also specify the content type contained in the block. - -````text -```shell -oc get pods -``` -```` - -which will produce: - -``` shell -oc get pods -``` - -Notice that the block automatically gets the *copy to clipboard* link to allow easy copy and paste. - -Every code block needs to identify the content. Where there is no content type, then **text** should be used to identify the content as plain text. Some of the common content types are shown in the table below. However, a full link of supported content types can be found [here](https://pygments.org/docs/lexers/){: target="_blank"}, where the short name in the documentation should be used. - -| type | Content -|------|-------- -| **shell** | Shell script content -| **powershell** | Windows Power Shell content -| **bat** | Windows batch file (.bat or .cmd files) -| **json** | JSON content -| **yaml** | YAML content -| **markdown** or **md** | Markdown content -| **java** | Java programming language -| **javascript** or **js** | JavaScript programming language -| **typescript** or **ts** | TypeScript programming language -| **text** | Plain text content - -#### Advanced highlighting of code blocks - -There are some additional features available due to the highlight plugin installed in MkDocs. Full details can be found in the [MkDocs Materials documentation](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/){: target=_blank}. - -#### Line numbers - -You can add line numbers to a code block with the **linenums** directive. You must specify the starting line number, 1 in the example below: - -```` md -``` javascript linenums="1" - -``` -```` - -creates - -``` javascript linenums="1" - -``` - -!!!Info - The line numbers do not get included when the copy to clipboard link is selected - -## Spell checking - -This project uses [cSpell](https://github.com/streetsidesoftware/cspell){: target=_blank} to check spelling within the markdown. The configuration included in the project automatically excludes content in a code block, enclosed in triple back quotes \`\`\`. - -The configuration file also specifies that US English is the language used in the documentation, so only US English spellings should be used for words where alternate international English spellings exist. - -You can add words to be considered valid either within a markdown document or within the cspell configuration file, **cspell.json**, in the root folder of the documentation repository. - -Words defined within a page only apply to that page, but words added to the configuration file apply to the entire project. - -### Adding local words - -You can add a list of words to be considered valid for spell checking purposes as a comment in a Markdown file. - -The comment has a specific format to be picked up by the cSpell tool: - -`````` - -here the words *linkchecker*, *linkcheckerrc*, *mkdocs* and *mkdoc* are specified as words to be accepted by the spell checker within the file containing the comment. - -### Adding global words - -The cSpell configuration file **cspell.json** contains a list of words that should always be considered valid when spell checking. The list of words applies to all files being checked. diff --git a/mkdocs.yml b/mkdocs.yml index ecf7a7f..3e82695 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,6 +90,8 @@ nav: - Documentation: - Overview: wg_docs/overview.md - Modifying OKD.io: wg_docs/okd-io.md + - Setup environment : wg_docs/doc-env.md + - Content guidelines : wg_docs/content.md - CRC Build: - Overview: wg_crc/overview.md - OKD Virtualization: diff --git a/package.json b/package.json index 0eb959b..6eb3b0e 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ "build": "./build.sh", "docker-build-image": "docker build -t mkdocs-build -f ./dev/Dockerfile .", "docker-serve": "docker run -it --rm --name mkdocs-serve -p 8000:8000 -v ${INIT_CWD}:/site mkdocs-build", - "docker-build": "docker run -it --rm --name mkdocs-build -p 8000:8000 -v ${INIT_CWD}:/site --entrypoint /site/build.sh mkdocs-build", + "docker-build": "docker run -it --rm --name mkdocs-build -v ${INIT_CWD}:/site --entrypoint /site/build.sh mkdocs-build", "podman-build-image": "podman build -t mkdocs-build -f ./dev/Dockerfile .", "podman-serve": "podman run -it --rm --name mkdocs-serve -p 8000:8000 -v ${INIT_CWD}:/site mkdocs-build", "podman-build": "podman run -it --rm --name mkdocs-build -v ${INIT_CWD}:/site --entrypoint /site/build.sh mkdocs-build",