diff --git a/README.md b/README.md index 1fdc78519b..fae9adc0d3 100644 --- a/README.md +++ b/README.md @@ -3,79 +3,71 @@ [![All Contributors](https://img.shields.io/badge/all_contributors-99-orange.svg?style=flat-square)](#contributors-) - ## Introduction -_With Rocky Linux emerging as a major RHEL-compatible distribution, this is an exciting time in the open source community. Rocky Linux’s [mission](https://rockylinux.org/community-charter/) is to provide companies and individuals with a **stable foundation of open source software** for their enterprise and HPC needs. We are here to support that mission with excellent documentation._ +*With Rocky Linux emerging as a major RHEL-compatible distribution, this is an exciting time in the open source community. Rocky Linux’s [mission](https://rockylinux.org/community-charter/) is to provide companies and individuals with a **stable foundation of open source software** for their enterprise and HPC needs. We are here to support that mission with excellent documentation.* To us, excellent documentation hits these marks: - -* Educate users on how to admin this distribution and its associated programs. -* Support users of all skill levels with manuals and troubleshooting guides to make the most of this distribution. -* Apply a consistent standard across all related documents, for ease of reading and translation. -* Keep documentation up to date (and error free) with current versions. -* Allow users to contribute Guides, Docs, Gemstones (scripts and favorite code snippets) and more, to enhance Rocky Linux for fellow users. +- Educate users on how to admin this distribution and its associated programs. +- Support users of all skill levels with manuals and troubleshooting guides to make the most of this distribution. +- Apply a consistent standard across all related documents, for ease of reading and translation. +- Keep documentation up to date (and error free) with current versions. +- Allow users to contribute Guides, Docs, Gemstones (scripts and favorite code snippets) and more, to enhance Rocky Linux for fellow users. We welcome anyone who wants to be part of this mission. No specific degree, years of experience, or company affiliation is required. Be bold! We promise, you won’t break anything even if you fumble your first attempt. ## License -Documents written by the _rocky linux documentation team_ are published under the Creative Commons-BY-SA license. This means you are free to copy, distribute and transform the works, while respecting the author's rights. +Documents written by the *rocky linux documentation team* are published under the Creative Commons-BY-SA license. This means you are free to copy, distribute and transform the works, while respecting the author's rights. -* **BY**: Attribution. You must cite the name of the original author. -* **SA**: Share Alike. +- **BY**: Attribution. You must cite the name of the original author. +- **SA**: Share Alike. [Creative Commons-BY-SA license](https://creativecommons.org/licenses/by-sa/4.0/) The documents and their sources are freely downloadable from: -* [https://docs.rockylinux.org](https://docs.rockylinux.org/) -* [https://github.com/rocky-linux/documentation](https://github.com/rocky-linux/documentation) +- +- Our media sources are hosted at github.com. You'll find the source code repository where the version of this document was created. ## Technical requirements -_Our standards for Rocky documentation._ +*Our standards for Rocky documentation.* ### Style Guide -The RL [Style Guide](https://docs.rockylinux.org/guides/contribute/style_guide/) outlines standards for the wording within your document. +The RL [Style Guide](https://docs.rockylinux.org/guides/contribute/style_guide/) outlines standards for the wording within your document. ### GitHub -Rocky Linux uses GitHub to manage its code and files, including documentation files. Login to GitHub and follow the official [Rocky Linux documentation repository](https://github.com/rocky-linux/documentation). - +Rocky Linux uses GitHub to manage its code and files, including documentation files. Login to GitHub and follow the official [Rocky Linux documentation repository](https://github.com/rocky-linux/documentation). ### Markdown -Documentation is welcome in whatever format you are used to creating. It does not need to be perfect, just submit what you have and the team will give you feedback to help get it in line with our voice and tone. +Documentation is welcome in whatever format you are used to creating. It does not need to be perfect, just submit what you have and the team will give you feedback to help get it in line with our voice and tone. -That said, RL Documentation uses Markdown as the standard. It is easy to learn and use. Run a text converter on your content or start from scratch with this [basic writing and formatting guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). For more information on writing markdown with proper formatting, see [our guide](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting). +That said, RL Documentation uses Markdown as the standard. It is easy to learn and use. Run a text converter on your content or start from scratch with this [basic writing and formatting guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). For more information on writing markdown with proper formatting, see [our guide](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting). As you become a regular contributor, you’ll need to create a **local repository**. See our [guide](https://docs.rockylinux.org/guides/contribute/beginners) for how to install a Markdown editor and create a local repository on your home computer. - ## Contribution Process -_The actual process of reporting an issue, revising, or creating a doc. Please see special notes afterward about translations, links, and meta content._ - +*The actual process of reporting an issue, revising, or creating a doc. Please see special notes afterward about translations, links, and meta content.* ### Report an issue Maybe you’ve found a broken link or incorrect information while exploring the Rocky docs. This is called an **issue**, and we want to know about it. You can mention it on the Mattermost Documentation channel, or visit GitHub and make a proper issue report. GitHub has [a handy guide](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) for how to create an issue. - ### Submit an update -_Add a missing word, correct an error, or clarify a confusing bit of text. You won’t break anything because someone will review your contribution before it goes live. Here is the basic process._ +*Add a missing word, correct an error, or clarify a confusing bit of text. You won’t break anything because someone will review your contribution before it goes live. Here is the basic process.* +1. Start on the page you want to update on . - -1. Start on the page you want to update on [https://docs.rockylinux.org/](https://docs.rockylinux.org/). - - Click the “Edit” pencil in the upper right corner of the document. You will be taken to the original document stored on GitHub. + Click the “Edit” pencil in the upper right corner of the document. You will be taken to the original document stored on GitHub. The first time you contribute to the RL repository, you will be prompted with a green button to “**Fork** this **repository** and propose changes.” This creates a duplicate copy of the RL repository where you make your suggested edits. Click the green button and continue. @@ -89,7 +81,7 @@ _Add a missing word, correct an error, or clarify a confusing bit of text. You w Then click Propose changes, which will **Commit** your changes to a completed document within your forked repository. -4. Review changes +4. Review changes Now you can look at what you’ve done, line by line. If you missed anything, back up to the previous page and correct it again (you’ll have to start over), then click Propose Changes again. @@ -105,9 +97,9 @@ _Add a missing word, correct an error, or clarify a confusing bit of text. You w Once the RL team reviews your request, they will respond in one of three ways. - * Accept and merge your PR - * Comment with feedback and ask for changes - * Deny your PR with explanation + - Accept and merge your PR + - Comment with feedback and ask for changes + - Deny your PR with explanation If you have to make changes, you will suddenly understand why you need a local repository. The team can [talk you through](https://chat.rockylinux.org/rocky-linux/channels/documentation) what to do next. In good news, it’s still fixable. @@ -115,18 +107,15 @@ Need more in-depth explanation? Here are the [same directions](https://docs.rock Success? Welcome to the team, you are officially a Rocky Linux documentation contributor. Your profile will be added to the contributor list at the bottom of this document shortly. - ### Become a frequent contributor For more than a word or two of occasional edits, we recommend that you [setup a local repository](https://docs.rockylinux.org/guides/contribute/createnew) on your own machine. From there, you can revise documentation from your clone of the RL repository, Commit it to your online GitHub repository, and then create Pull Requests to merge with the main repository. Advanced users may wish to create a complete documentation server on your local Linux workstation or VM. We have guides to set that up with [Docker](https://docs.rockylinux.org/guides/contribute/localdocs/rockydocs_web_dev/) or [LXD](https://docs.rockylinux.org/guides/contribute/localdocs/mkdocs_lsyncd/). We also have a [fast documentation system](https://docs.rockylinux.org/guides/contribute/localdocs/local_docs/) with special caveats if you are using Python on the same server. - ### Submit a new document -_Rocky Linux documentation includes guides, books, labs, and [gemstones](https://docs.rockylinux.org/gemstones/). Your original contributions are welcome in any of these categories._ - +*Rocky Linux documentation includes guides, books, labs, and [gemstones](https://docs.rockylinux.org/gemstones/). Your original contributions are welcome in any of these categories.* #### Meta @@ -134,7 +123,7 @@ Please include the following **meta** information at the top of all new document --- -title: Document title +title: Document title author: the author of the source (English) version of the document. @@ -142,81 +131,71 @@ contributors: a comma separated list of contributors to the source document. tested with: a comma separated list of versions, for example 8.6, 9.0 -tags: +tags: - - displayable tags +- displayable tags - - these are also searchable +- these are also searchable - - they are two space indented and start with a "-" as shown here +- they are two space indented and start with a "-" as shown here - - generally, they should be one word +- generally, they should be one word --- - #### Formatting To add more advanced elements to your Markdown-formatted document beyond text, visit the [formatting guide](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/). This covers Admonitions, Tables, Quotes, and more. - #### Contribute The process for [submitting original content](https://docs.rockylinux.org/guides/contribute/createnew) is similar to updating an existing document from your local repository. Create a new document within your Markdown editor, Commit it to your GitHub repository, then submit a Pull Request to merge into the main branch of the repository. The documentation leads will decide where the new document will live. - ## Special Notes - ### Links Links can be internal (other docs within our domain), external (publicly hosted URLs), or lab-based (used as examples within your document). -The format for all links within the documentation is square brackets around the descriptive name or label: +The format for all links within the documentation is square brackets around the descriptive name or label: -[our site] followed by your link in parenthesis: (https://example.com) +[our site] followed by your link in parenthesis: () To help lab-based URLs pass our automatic URL checker, we have created a list of excluded names you may use. You may request that a new exclusion be added. An editor may adjust your lab-based URL, or add an exclusion if they think it is warranted. Please note the following IEEE recommendation on naming local networks [RFC #8375 Special-Use Domain 'home.arpa.'](https://www.rfc-editor.org/rfc/rfc8375.html) published in May 2018. +- home.arpa +- example.com +- site.com +- site1.com +- site2.com +- apache-server +- nginx-server +- your-server-ip +- your-server-hostname +- localhost -* home.arpa -* example.com -* site.com -* site1.com -* site2.com -* apache-server -* nginx-server -* your-server-ip -* your-server-hostname -* localhost - - -### Translation - +### Translation #### CrowdIn -We are adding to these docs in new languages at the speed of getting translators on board. Seeking contributors for this area especially. We use [CrowdIn](https://crowdin.com/) for updates. - +We are adding to these docs in new languages at the speed of getting translators on board. Seeking contributors for this area especially. We use [CrowdIn](https://crowdin.com/) for updates. #### Translation and Meta content -Translators, if you find a word in the source document that does not translate well into your language, or an error that prevents a perfect translation, please fix that in the source document and make a Pull Request. In that case, please add yourself as a contributor in the meta content of that document. +Translators, if you find a word in the source document that does not translate well into your language, or an error that prevents a perfect translation, please fix that in the source document and make a Pull Request. In that case, please add yourself as a contributor in the meta content of that document. However, unless you modify the source document, please do not modify the meta content. -The place where we do want to acknowledge you is in the all-contributors section--at the bottom of this page. This is a list of everyone who has been part of this documentation project, whether creating content, spotting and fixing errors, or translating. Translators, you may add yourself (or [request to be added](https://chat.rockylinux.org/rocky-linux/channels/documentation)) here. We appreciate your contribution! - +The place where we do want to acknowledge you is in the all-contributors section--at the bottom of this page. This is a list of everyone who has been part of this documentation project, whether creating content, spotting and fixing errors, or translating. Translators, you may add yourself (or [request to be added](https://chat.rockylinux.org/rocky-linux/channels/documentation)) here. We appreciate your contribution! ## Communication channel -_For reporting issues, asking questions, getting support, and getting to know the documentarians._ +*For reporting issues, asking questions, getting support, and getting to know the documentarians.* For general questions about installing and using the distro, visit our [community forums](https://forums.rockylinux.org). For questions about the behind-the-scenes stuff like documentation, we have other channels. - ### Mattermost To ask real-time questions, create a profile on the [Mattermost](https://mattermost.com/) server, then navigate to the Rocky Linux [General](https://chat.rockylinux.org/rocky-linux/channels/town-square) or [Documentation](https://chat.rockylinux.org/rocky-linux/channels/documentation) channel--or whichever channel seems appropriate to your question. You should get a response within hours if not right away. diff --git a/docs/guides/contribute/beginners.md b/docs/guides/contribute/beginners.md index a3fe381c35..1829a78257 100644 --- a/docs/guides/contribute/beginners.md +++ b/docs/guides/contribute/beginners.md @@ -11,7 +11,7 @@ tags: # First-Time Contributor Guide -_Everybody starts somewhere. If this is the first time you have contributed to open source documentation on GitHub, congratulations on taking this step. We can not wait to see what you have to say!_ +*Everybody starts somewhere. If this is the first time you have contributed to open source documentation on GitHub, congratulations on taking this step. We can not wait to see what you have to say!* ## Git and GitHub @@ -23,20 +23,20 @@ You may not start out creating and managing repositories for Rocky Linux, but th Markdown is an easy language that allows you to include formatting, code, and plain text in the same file. The first time you update a document, follow the existing code. It will not be long before you are ready to explore additional features. When the time comes, here are the basics. -* [Basic Markdown](https://www.markdownguide.org/basic-syntax#code) -* [Extended Markdown](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) -* Some of the more [advanced formatting](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) options we use in our repository +- [Basic Markdown](https://www.markdownguide.org/basic-syntax#code) +- [Extended Markdown](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) +- Some of the more [advanced formatting](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) options we use in our repository ## Local repository editor To create a local repository, first find and install a Markdown editor that works with your computer and operating system. Here are some options, but there are others. Use what you know. -* [ReText](https://github.com/retext-project/retext) - Free, cross-platform, and open source -* [Zettlr](https://www.zettlr.com/) - Free, cross-platform, and open source -* [MarkText](https://github.com/marktext/marktext) - Free, cross-platform, and open source -* [Remarkable](https://remarkableapp.github.io/) - Linux and Windows, open source -* [NvChad](https://nvchad.com/) for the vi/vim user and the nvim client. A lot of plugins are available to enhance the editor for markdown. See [this document](https://docs.rockylinux.org/books/nvchad/) for a nice set of installation instructions. -* [VS Code](https://code.visualstudio.com/) - Partially open source, by Microsoft. VS Code is a lightweight and powerful editor available for Windows, Linux and MacOS. To contribute to this document project, you should get the following extensions: Git Graph, HTML Preview, HTML Snippets, Markdown All in One, Markdown Preview Enhanced, Markdown Preview Mermaid Support, and any more that catch your fancy. +- [ReText](https://github.com/retext-project/retext) - Free, cross-platform, and open source +- [Zettlr](https://www.zettlr.com/) - Free, cross-platform, and open source +- [MarkText](https://github.com/marktext/marktext) - Free, cross-platform, and open source +- [Remarkable](https://remarkableapp.github.io/) - Linux and Windows, open source +- [NvChad](https://nvchad.com/) for the vi/vim user and the nvim client. A lot of plugins are available to enhance the editor for markdown. See [this document](https://docs.rockylinux.org/books/nvchad/) for a nice set of installation instructions. +- [VS Code](https://code.visualstudio.com/) - Partially open source, by Microsoft. VS Code is a lightweight and powerful editor available for Windows, Linux and MacOS. To contribute to this document project, you should get the following extensions: Git Graph, HTML Preview, HTML Snippets, Markdown All in One, Markdown Preview Enhanced, Markdown Preview Mermaid Support, and any more that catch your fancy. ## Create a local repository @@ -52,7 +52,7 @@ Once you have a Markdown editor installed, follow instructions to connect it to ## Submit an update -_Add a missing word, correct an error, or clarify a confusing bit of text._ +*Add a missing word, correct an error, or clarify a confusing bit of text.* 1. Start on the page you want to update. @@ -90,9 +90,9 @@ _Add a missing word, correct an error, or clarify a confusing bit of text._ Once the RL team gets your request, they will respond in one of three ways. - * Accept and merge your PR - * Comment with feedback and ask for changes - * Deny your PR with an explanation + - Accept and merge your PR + - Comment with feedback and ask for changes + - Deny your PR with an explanation The last response is unlikely. We really want to include your perspective here! If you have to make changes, you will suddenly understand why you need a local repository. The team can [talk you through](https://chat.rockylinux.org/rocky-linux/channels/documentation) what to do next. In good news, it’s still fixable. Follow the comment section of that request to see what further information is requested. diff --git a/docs/guides/contribute/createnew.md b/docs/guides/contribute/createnew.md index 03a67e93d2..2ce71b8751 100644 --- a/docs/guides/contribute/createnew.md +++ b/docs/guides/contribute/createnew.md @@ -9,40 +9,59 @@ tags: # How To Create a New Document in GitHub -_When you are ready to submit your original written documentation for approval, follow these easy steps:_ - +*When you are ready to submit your original written documentation for approval, follow these easy steps:* ## With the GitHub GUI You can complete almost all tasks from the web GUI on GitHub. Here's an example of adding a file you've created on your local machine to the Rocky Linux documentation GitHub repository. - - 1. Login to your GitHub account. -2. Navigate to the Rocky Linux Documentation repository at [https://github.com/rocky-linux/documentation](https://github.com/rocky-linux/documentation). +2. Navigate to the Rocky Linux Documentation repository at . 3. You should be on the "Main" branch, so check the drop-down label down in the middle section to be sure you are. Your document might not ultimately end up in the "Main" branch, but admins will move it around to where it logically fits later. -4. On the right-hand side of the page, click the "Fork" button, which will create your copy of the documentation. -5. In the middle of the page on the forked copy, just to the left of the Green "Code" drop-down, is an "Add file" button. Click this and choose the "Upload files" option. +4. On the right-hand side of the page, click the ++"Fork"++ button, which will create your copy of the documentation. +5. In the middle of the page on the forked copy, just to the left of the Green "Code" drop-down, is an ++"Add file"++ button. Click this and choose the "Upload files" option. 6. This will allow you to drag and drop files here or browse to them on your computer. Go ahead and use the method that you prefer. 7. Once the file is uploaded, the next thing you need to do is create a Pull Request. This request lets the upstream administrators know you have a new file (or files) that you want them to merge with the master branch. -8. Click on "Pull Request" in the upper-left corner of the screen. +8. Click on `Pull Request` in the upper-left corner of the screen. 9. Write a brief message in the "Write" section letting the administrators know what you've done. (New document, revision, suggested change, etc.) then submit your change. - ## From the Git Command-Line If you prefer to run Git locally on your machine, you can clone the [Rocky Linux Documentation](https://github.com/rocky-linux/documentation) repository, make changes, and then commit changes afterward. To make things simple, execute steps 1-3 using the **With the GitHub GUI** approach above, then: +1. Git clone the repository: + ```text + git clone https://github.com/your_fork_name/documentation.git + ``` -1. Git clone the repository: git clone https://github.com/your_fork_name/documentation.git 2. Now, on your machine, add files to the directory. -3. Example: mv /home/myname/help.md /home/myname/documentation/ -4. Next, run Git add for that file name. -5. Example: git add help.md -6. Now, run git commit for the changes you have made. -7. Example: git commit -m "Added the help.md file" -8. Next, push your changes to your forked repository: git push https://github.com/your_fork_name/documentation main -9. Next, repeat steps 6 and 7 above: Create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master branch. Click on "Pull Request" in the upper-left corner of the screen. - -Watch for comments within the PR for requested revisions and clarifications. + Example: + + ```bash + mv /home/myname/help.md /home/myname/documentation/ + ``` + +3. Next, run Git add for that file name. + Example: + + ```text + git add help.md + ``` + +4. Now, run git commit for the changes you have made. + Example: + + ```text + git commit -m "Added the help.md file" + ``` + +5. Next, push your changes to your forked repository: + + ```text + git push https://github.com/your_fork_name/documentation main + ``` + +6. Next, repeat steps 6 and 7 above: Create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master branch. Click on `Pull Request` in the upper-left corner of the screen. + +Watch for comments within the PR for requested revisions and clarifications. diff --git a/docs/guides/contribute/localdocs/local_docs.md b/docs/guides/contribute/localdocs/local_docs.md index 8ddd55bbc8..5a0bb6c2ea 100644 --- a/docs/guides/contribute/localdocs/local_docs.md +++ b/docs/guides/contribute/localdocs/local_docs.md @@ -14,35 +14,35 @@ You can build the documentation system locally without either Docker or LXD if y ## Procedure -* Clone the docs.rockylinux.org repository: +- Clone the docs.rockylinux.org repository: -``` -git clone https://github.com/rocky-linux/docs.rockylinux.org.git -``` + ```bash + git clone https://github.com/rocky-linux/docs.rockylinux.org.git + ``` -* Once finished, change into the docs.rockylinux.org directory: +- Once finished, change into the docs.rockylinux.org directory: -``` -cd docs.rockylinux.org -``` + ```bash + cd docs.rockylinux.org + ``` -* Now clone the documentation repository using: +- Now clone the documentation repository using: -``` -git clone https://github.com/rocky-linux/documentation.git docs -``` + ```bash + git clone https://github.com/rocky-linux/documentation.git docs + ``` -* Next, install the requirements.txt file for mkdocs: +- Next, install the requirements.txt file for mkdocs: -``` -python3 -m pip install -r requirements.txt -``` + ```bash + python3 -m pip install -r requirements.txt + ``` -* Finally run the mkdocs server: +- Finally run the mkdocs server: -``` -mkdocs serve -``` + ```text + mkdocs serve + ``` ## Conclusion diff --git a/docs/guides/contribute/localdocs/mkdocs_lsyncd.md b/docs/guides/contribute/localdocs/mkdocs_lsyncd.md index 5f288b5c9f..d539828de8 100644 --- a/docs/guides/contribute/localdocs/mkdocs_lsyncd.md +++ b/docs/guides/contribute/localdocs/mkdocs_lsyncd.md @@ -18,14 +18,14 @@ This is also a companion document to the [Docker version here](rockydocs_web_dev ## Prerequisites and assumptions -* Familiarity and comfort with the command-line -* Comfortable using tools for editing, SSH, and synchronization, or willing to follow along and learn -* LXD reference - there is a long document on [building and using LXD on a server here](../../../books/lxd_server/00-toc.md), but you will use just a basic install on our Linux workstation -* Using `lsyncd` for mirroring files. See [documentation on that here](../../backup/mirroring_lsyncd.md) -* You will need public keys generated for your user and the "root" user on your local workstation using [this document](../../security/ssh_public_private_keys.md) -* Our bridge interface is running on 10.56.233.1 and our container is running on 10.56.233.189 in our examples. However your IPs for the bridge and container will be different. -* "youruser" in this document represents your user id -* The assumption is that you are already doing documentation development with a clone of the documentation repository on your workstation +- Familiarity and comfort with the command-line +- Comfortable using tools for editing, SSH, and synchronization, or willing to follow along and learn +- LXD reference - there is a long document on [building and using LXD on a server here](../../../books/lxd_server/00-toc.md), but you will use just a basic install on our Linux workstation +- Using `lsyncd` for mirroring files. See [documentation on that here](../../backup/mirroring_lsyncd.md) +- You will need public keys generated for your user and the "root" user on your local workstation using [this document](../../security/ssh_public_private_keys.md) +- Our bridge interface is running on 10.56.233.1 and our container is running on 10.56.233.189 in our examples. However your IPs for the bridge and container will be different. +- "youruser" in this document represents your user id +- The assumption is that you are already doing documentation development with a clone of the documentation repository on your workstation ## The `mkdocs` container @@ -35,13 +35,13 @@ Our first step is to create the LXD container. Using your container's defaults ( You will add a Rocky container to our workstation for `mkdocs`. Just name it "mkdocs": -``` +```bash lxc launch images:rockylinux/8 mkdocs ``` The container needs to be a proxy. By default, when `mkdocs serve` starts, it runs on 127.0.0.1:8000. That is fine when it is on your local workstation without a container. However, when it is in an LXD **container** on your local workstation, you need to set up the container with a proxy port. Do this with: -``` +```bash lxc config device add mkdocs mkdocsport proxy listen=tcp:0.0.0.0:8000 connect=tcp:127.0.0.1:8000 ``` @@ -55,7 +55,7 @@ In the line above, "mkdocs" is our container name, "mkdocsport" is an arbitrary First, get into the container with: -``` +```bash lxc exec mkdocs bash ``` @@ -77,22 +77,21 @@ lxc exec mkdocs bash For Rocky Linux 9.x you will need a few packages (see "Changes in requirements.txt for 8.x" for 8.x package installation!): -``` +```bash dnf install git openssh-server python3-pip rsync ``` When installed, you need to enable and start `sshd`: - -``` +```bash systemctl enable --now sshd ``` + ### Container users You need to set a password for our root user and then add our user (the user you use on your local machine) to the sudoers list. You are the "root" user at the moment. To change the password enter: - -``` +```text passwd ``` @@ -100,14 +99,14 @@ Set a secure and memorable password. Next, add your user and set a password: -``` +```bash adduser youruser passwd youruser ``` Add your user to the sudoers group: -``` +```bash usermod -aG wheel youruser ``` @@ -117,13 +116,13 @@ You should be able to SSH into the container with the root user or your user fro In this procedure, the root user (at minimum) needs to be able to SSH into the container without entering a password; this is because of the `lsyncd` process you will be implementing. The assumption here is that you can sudo to the root user on your local workstation: -``` +```bash sudo -s ``` The assumption also is that the root user has an `id_rsa.pub` key in the `./ssh` directory. If not, generate one with [this procedure](../../security/ssh_public_private_keys.md): -``` +```bash ls -al .ssh/ drwx------ 2 root root 4096 Feb 25 08:06 . drwx------ 14 root root 4096 Feb 25 08:10 .. @@ -134,46 +133,46 @@ drwx------ 14 root root 4096 Feb 25 08:10 .. To get SSH access on our container without having to enter a password, provided the `id_rsa.pub` key exists, as it does above, just run: -``` +```bash ssh-copy-id root@10.56.233.189 ``` -For our user, however, you need the entire `.ssh/` directory copied to our container. You will keep everything the same for this user so that our access to GitHub over SSH is the same. +For our user, however, you need the entire `.ssh/` directory copied to our container. You will keep everything the same for this user so that our access to GitHub over SSH is the same. To copy everything over to our container, you just need to do this as your user, **not** sudo: -``` +```bash scp -r .ssh/ youruser@10.56.233.189:/home/youruser/ ``` Next, SSH into the container as your user: -``` +```bash ssh -l youruser 10.56.233.189 ``` -You need to make things identical. You are doing this with `ssh-add`. To do this, you must ensure that you have the ssh-agent available: +You need to make things identical. You are doing this with `ssh-add`. To do this, you must ensure that you have the `ssh-agent` available: -``` +```bash eval "$(ssh-agent)" ssh-add ``` ## Cloning repositories -You need two repositories cloned, but no need to add any git remotes. The documentation repository here will only display the current documentation (mirrored from your workstation) and the docs. +You need two repositories cloned, but no need to add any `git` remotes. The documentation repository here will only display the current documentation (mirrored from your workstation) and the docs. The rockylinux.org repository is for running `mkdocs serve` and will use the mirror as its source. Run all these steps as your non-root user. If you are not able to clone the repositories as your userid, then there **IS** a problem with your identity as far as `git` is concerned and you will need to review the last few steps for re-creating your key environment (above). First, clone the documentation: -``` +```bash git clone git@github.com:rocky-linux/documentation.git ``` Next, clone docs.rockylinux.org: -``` +```bash git clone git@github.com:rocky-linux/docs.rockylinux.org.git ``` @@ -181,40 +180,41 @@ If you get errors, return to the steps above and ensure that those are all corre ## Setting up `mkdocs` -Installing the needed plugins is all done with `pip3` and the "requirements.txt" file in the docs.rockylinux.org directory. While this process will argue with you about using the root user to write the changes to the system directories, you have to run it as root. +Installing the needed plugins is all done with `pip3` and the "requirements.txt" file in the docs.rockylinux.org directory. While this process will argue with you about using the root user to write the changes to the system directories, you have to run it as root. You do this with `sudo` here. Change into the directory: -``` +```bash cd docs.rockylinux.org ``` Then run: -``` +```bash sudo pip3 install -r requirements.txt ``` Next you must set up `mkdocs` with an additional directory. `mkdocs` requires the creation of a docs directory and then the documentation/docs directory linked beneath it. Do this with: -``` +```bash mkdir docs cd docs ln -s ../../documentation/docs ``` + ### Testing `mkdocs` Now that you have `mkdocs` setup, try starting the server. Remember, this process will argue that it looks like this is production. It is not, so ignore the warning. Start `mkdocs serve` with: -``` +```bash mkdocs serve -a 0.0.0.0:8000 ``` You will see something like this in the console: -``` +```bash INFO - Building documentation... WARNING - Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please @@ -243,12 +243,13 @@ Now for the moment of truth! If you have done everything correctly, you should b In our example, enter the following in the browser address (**NOTE** To avoid broken URLs, the IP here has been changed to "your-server-ip". You just need to substitute in the IP): -``` +```bash http://your-server-ip:8000 ``` + ## `lsyncd` -You are almost there if you saw the documentation in the web browser. The last step is to keep the documentation in your container synchronized with the one on your local workstation. +You are almost there if you saw the documentation in the web browser. The last step is to keep the documentation in your container synchronized with the one on your local workstation. As noted above, you are doing this here with `lsyncd`. @@ -261,31 +262,31 @@ For now, we are assuming that you are using a Rocky Linux workstation and are us ### Configuration !!! Note - + The root user must run the daemon, so you must be root to create the configuration files and logs. For this we are assuming `sudo -s`. You need to have some log files available for `lsyncd` to write to: -``` +```bash touch /var/log/lsyncd-status.log touch /var/log/lsyncd.log ``` You also need to have an exclude file created, even though in this case you are not excluding anything: -``` +```bash touch /etc/lsyncd.exclude ``` Finally you need to create the configuration file. In this example, we are using `vi` as our editor, but you may use whichever editor you feel comfortable with: -``` +```bash vi /etc/lsyncd.conf ``` Then place this content in that file and save it. Be sure to replace "youruser" with your actual user, and the IP address with your own container IP: -``` +```bash settings { logfile = "/var/log/lsyncd.log", statusFile = "/var/log/lsyncd-status.log", @@ -312,13 +313,13 @@ sync { Assuming that you enabled `lsyncd` when you installed it, at this point you need just to start or restart the process: -``` +```bash systemctl restart lsyncd ``` To ensure things are working, check the logs-particularly the `lsyncd.log`, which should show you something like this if everything started correctly: -``` +```bash Fri Feb 25 08:10:16 2022 Normal: --- Startup, daemonizing --- Fri Feb 25 08:10:16 2022 Normal: recursive startup rsync: /home/youruser/documentation/ -> root@10.56.233.189:/home/youruser/documentation/ Fri Feb 25 08:10:41 2022 Normal: Startup of "/home/youruser/documentation/" finished: 0 diff --git a/docs/guides/contribute/localdocs/rockydocs_web_dev.md b/docs/guides/contribute/localdocs/rockydocs_web_dev.md index d7942ee5d8..03f164b1c6 100644 --- a/docs/guides/contribute/localdocs/rockydocs_web_dev.md +++ b/docs/guides/contribute/localdocs/rockydocs_web_dev.md @@ -11,95 +11,88 @@ This document walks through how to recreate and run a local copy of the entire d Running a local copy of the documentation website might be useful in the following scenarios: -* You are interested in learning about and contributing to the web development aspects of the docs.rockylinux.org website -* You are an author and you'd like to see how your documents will render/look on the docs website before contributing them -* You are a web developer looking to contribute to or help maintain the docs.rockylinux.org website +- You are interested in learning about and contributing to the web development aspects of the docs.rockylinux.org website +- You are an author and you'd like to see how your documents will render/look on the docs website before contributing them +- You are a web developer looking to contribute to or help maintain the docs.rockylinux.org website +## Some notes -### Some notes: - -* The instructions in this guide are **NOT** a prerequisite for Rocky documentation Authors/Content contributors -* The entire environment runs in a Docker container and so you'll need a Docker engine on your local machine -* The container is built on top of the official RockyLinux docker image available here https://hub.docker.com/r/rockylinux/rockylinux -* The container keeps the documentation content (guides, books, images and so on) separate from the web engine (mkdocs) -* The container starts a local web server listening on port 8000. And port 8000 will be forwarded to the Docker host - +- The instructions in this guide are **NOT** a prerequisite for Rocky documentation Authors/Content contributors +- The entire environment runs in a Docker container and so you'll need a Docker engine on your local machine +- The container is built on top of the official RockyLinux docker image available here +- The container keeps the documentation content (guides, books, images and so on) separate from the web engine (mkdocs) +- The container starts a local web server listening on port 8000. And port 8000 will be forwarded to the Docker host ## Create the content environment 1. Change the current working directory on your local system to a folder where you intend to do your writing. We'll refer to this directory as `$ROCKYDOCS` in the rest of this guide. For our demo here, `$ROCKYDOCS` points to `~/projects/rockydocs` on our demo system. -Create $ROCKYDOCS if it doesn't already exist and then type: + Create $ROCKYDOCS if it doesn't already exist and then type: -``` -cd $ROCKYDOCS -``` + ```bash + cd $ROCKYDOCS + ``` 2. Make sure you have `git` installed (`dnf -y install git`). While in $ROCKYDOCS use git to clone the official Rocky Documentation content repo. Type: -``` -git clone https://github.com/rocky-linux/documentation.git -``` + ```bash + git clone https://github.com/rocky-linux/documentation.git + ``` You'll now have a `$ROCKYDOCS/documentation` folder. This folder is a git repository and under git's control. - ## Create and Start the RockyDocs web development environment -3. Make sure you have Docker up and running on your local machine (you can check with `systemctl`) +1. Make sure you have Docker up and running on your local machine (you can check with `systemctl`) -4. From a terminal type: +2. From a terminal type: -``` -docker pull wsoyinka/rockydocs:latest -``` + ```bash + docker pull wsoyinka/rockydocs:latest + ``` -5. Check to make sure the image downloaded successfully. Type: +3. Check to make sure the image downloaded successfully. Type: -``` -docker image ls -``` + ```bash + docker image ls + ``` ## Start the RockyDocs container 1. Start a container from the rockydocs image. Type: -``` -docker run -it --name rockydoc --rm \ - -p 8000:8000 \ - --mount type=bind,source="$(pwd)"/documentation,target=/documentation \ - wsoyinka/rockydocs:latest - -``` - - -Alternatively if you prefer and if you have `docker-compose` installed, you can create compose file named `docker-compose.yml` with the following contents: - -``` -version: "3.9" -services: - rockydocs: - image: wsoyinka/rockydocs:latest - volumes: - - type: bind - source: ./documentation - target: /documentation - container_name: rocky - ports: - - "8000:8000" - -``` - -Save the file with the file name `docker-compose.yml` in your $ROCKYDOCS working directory. And start the service/container by running: - -``` -docker-compose up -``` - + ```bash + docker run -it --name rockydoc --rm \ + -p 8000:8000 \ + --mount type=bind,source="$(pwd)"/documentation,target=/documentation \ + wsoyinka/rockydocs:latest + ``` + + Alternatively if you prefer and if you have `docker-compose` installed, you can create compose file named `docker-compose.yml` with the following contents: + + ```bash + version: "3.9" + services: + rockydocs: + image: wsoyinka/rockydocs:latest + volumes: + - type: bind + source: ./documentation + target: /documentation + container_name: rocky + ports: + - "8000:8000" + ``` + + Save the file with the file name `docker-compose.yml` in your $ROCKYDOCS working directory. And start the service/container by running: + + ```bash + docker-compose up + ``` ## View the local docs.rockylinux.org website With the container up and running, you should now be able to point your web browser to the following URL to view your local copy of the site: -http://localhost:8000 + diff --git a/docs/guides/contribute/localdocs/rockydocs_webdev_v2.md b/docs/guides/contribute/localdocs/rockydocs_webdev_v2.md index 2b24c6fe7e..e013b59648 100644 --- a/docs/guides/contribute/localdocs/rockydocs_webdev_v2.md +++ b/docs/guides/contribute/localdocs/rockydocs_webdev_v2.md @@ -7,158 +7,146 @@ update: 13-Feb-2023 # Running the docs.rockylinux.org website locally for web development | Podman - This document walks through how to recreate and run a local copy of the entire docs.rockylinux.org website on your local machine. Running a local copy of the documentation website might be useful in the following scenarios: -* You are interested in learning about and contributing to the web development aspects of the docs.rockylinux.org website -* You are an author and you'd like to see how your documents will render/look on the docs website before contributing them - +- You are interested in learning about and contributing to the web development aspects of the docs.rockylinux.org website +- You are an author and you'd like to see how your documents will render/look on the docs website before contributing them ## Create the content environment -1. Ensure that the prerequisites are satisfied. If not please skip to the "[Setup the prerequisites](#setup-the-prerequisites)" section and then return here. +1. Ensure that the prerequisites are satisfied. If not please skip to the "[Setup the prerequisites](#setup-the-prerequisites)" section and then return here. -2. Change the current working directory on your local system to a folder where you intend to do your writing. +2. Change the current working directory on your local system to a folder where you intend to do your writing. We will refer to this directory as `$ROCKYDOCS` in the rest of this guide. For our demo here, `$ROCKYDOCS` points to `$HOME/projects/rockydocs` on our demo system. -Create $ROCKYDOCS if it doesn't already exist and change your working directory to $ROCKYDOCS type: + Create `$ROCKYDOCS` if it doesn't already exist and change your working directory to `$ROCKYDOCS` type: -``` -mkdir -p $HOME/projects/rockydocs -export ROCKYDOCS=${HOME}/projects/rockydocs -cd $ROCKYDOCS -``` + ```bash + mkdir -p $HOME/projects/rockydocs + export ROCKYDOCS=${HOME}/projects/rockydocs + cd $ROCKYDOCS + ``` 3. Ensure you have `git` installed (`dnf -y install git`). While in $ROCKYDOCS use git to clone the official Rocky Documentation content repo. Type: -``` -git clone https://github.com/rocky-linux/documentation.git -``` + ```bash + git clone https://github.com/rocky-linux/documentation.git + ``` -You will now have a `$ROCKYDOCS/documentation` folder. This folder is a git repository and under git's control. + You will now have a `$ROCKYDOCS/documentation` folder. This folder is a git repository and under git's control. 4. Also use `git` to clone the official docs.rockylinux.org repo. Type: -``` -git clone https://github.com/rocky-linux/docs.rockylinux.org.git -``` + ```bash + git clone https://github.com/rocky-linux/docs.rockylinux.org.git + ``` You will now have a `$ROCKYDOCS/docs.rockylinux.org` folder. This folder is where you can experiment with your web development contributions. - ## Create and Start the RockyDocs web development environment -5. Ensure you have Podman up and running on your local machine (you can check with `systemctl `). Test by running: - -``` -systemctl enable --now podman.socket -``` - -6. Create a new `docker-compose.yml` file with the following contents: - -``` -version: '2' -services: - mkdocs: - privileged: true - image: rockylinux:9.1 - ports: - - 8001:8001 - environment: - PIP_NO_CACHE_DIR: "off" - PIP_DISABLE_PIP_VERSION_CHECK: "on" - volumes: - - type: bind - source: ./documentation - target: /app/docs - - type: bind - source: ./docs.rockylinux.org - target: /app/docs.rockylinux.org - working_dir: /app - command: bash -c "dnf install -y python3 pip git && \ - ln -sfn /app/docs docs.rockylinux.org/docs && \ - cd docs.rockylinux.org && \ - git config --global user.name webmaster && \ - git config --global user.email webmaster@rockylinux.org && \ - curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/mike-plugin-changes.patch -o mike-plugin-changes.patch && \ - git apply --reverse --check mike-plugin-changes.patch && \ - /usr/bin/pip3 install --no-cache-dir -r requirements.txt && \ - /usr/local/bin/mike deploy -F mkdocs.yml 9.1 91alias && \ - /usr/local/bin/mike set-default 9.1 && \ - echo All done && \ - /usr/local/bin/mike serve -F mkdocs.yml -a 0.0.0.0:8001" - -``` - -Save the file with the file name `docker-compose.yml` in your $ROCKYDOCS working directory. - -You can also quickly download a copy of the docker-compose.yml file by running: - -``` -curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/docker-compose-rockydocs.yml -o docker-compose.yml -``` - - -7. Finally use docker-compose to bring up the service. Type: - -``` -docker-compose up -``` - +1. Ensure you have Podman up and running on your local machine (you can check with `systemctl`). Test by running: + + ```bash + systemctl enable --now podman.socket + ``` + +2. Create a new `docker-compose.yml` file with the following contents: + + ```bash + version: '2' + services: + mkdocs: + privileged: true + image: rockylinux:9.1 + ports: + - 8001:8001 + environment: + PIP_NO_CACHE_DIR: "off" + PIP_DISABLE_PIP_VERSION_CHECK: "on" + volumes: + - type: bind + source: ./documentation + target: /app/docs + - type: bind + source: ./docs.rockylinux.org + target: /app/docs.rockylinux.org + working_dir: /app + command: bash -c "dnf install -y python3 pip git && \ + ln -sfn /app/docs docs.rockylinux.org/docs && \ + cd docs.rockylinux.org && \ + git config --global user.name webmaster && \ + git config --global user.email webmaster@rockylinux.org && \ + curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/mike-plugin-changes.patch -o mike-plugin-changes.patch && \ + git apply --reverse --check mike-plugin-changes.patch && \ + /usr/bin/pip3 install --no-cache-dir -r requirements.txt && \ + /usr/local/bin/mike deploy -F mkdocs.yml 9.1 91alias && \ + /usr/local/bin/mike set-default 9.1 && \ + echo All done && \ + /usr/local/bin/mike serve -F mkdocs.yml -a 0.0.0.0:8001" + ``` + + Save the file with the file name `docker-compose.yml` in your $ROCKYDOCS working directory. + + You can also quickly download a copy of the docker-compose.yml file by running: + + ```bash + curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/docker-compose-rockydocs.yml -o docker-compose.yml + ``` + +3. Finally use docker-compose to bring up the service. Type: + + ```bash + docker-compose up + ``` ## View the local docs.rockylinux.org website -8. If you have a firewall running on your Rocky Linux system, ensure that port 8001 is open. Type: +If you have a firewall running on your Rocky Linux system, ensure that port 8001 is open. Type: -``` -firewall-cmd --add-port=8001/tcp --permanent -firewall-cmd --reload -``` + ```bash + firewall-cmd --add-port=8001/tcp --permanent + firewall-cmd --reload + ``` -With the container up and running, you should now be able to point your web browser to the following URL to view your local copy of the site: - -http://localhost:8001 - -OR - -http://SERVER_IP:8001 + With the container up and running, you should now be able to point your web browser to the following URL to view your local copy of the site: + + OR + ## Setup the prerequisites Install and setup Podman and other tools by running: -``` +```bash sudo dnf -y install podman podman-docker git sudo systemctl enable --now podman.socket - ``` Install docker-compose and make it executable. Type: -``` +```bash curl -SL https://github.com/docker/compose/releases/download/v2.16.0/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose chmod 755 /usr/local/bin/docker-compose ``` - Fix permissions on docker socket. Type: -``` +```bash sudo chmod 666 /var/run/docker.sock ``` +### Notes -### Notes: - -* The instructions in this guide are **NOT** a prerequisite for Rocky documentation authors or content contributors -* The entire environment runs in a Podman container and so you will need Podman properly setup on your local machine -* The container is built on top of the official Rocky Linux 9.1 docker image available here https://hub.docker.com/r/rockylinux/rockylinux -* The container keeps the documentation content separate from the web engine (mkdocs) -* The container starts a local web server listening on port 8001. +- The instructions in this guide are **NOT** a prerequisite for Rocky documentation authors or content contributors +- The entire environment runs in a Podman container and so you will need Podman properly setup on your local machine +- The container is built on top of the official Rocky Linux 9.1 docker image available here +- The container keeps the documentation content separate from the web engine (mkdocs) +- The container starts a local web server listening on port 8001. diff --git a/docs/guides/contribute/navigation.md b/docs/guides/contribute/navigation.md index 1f706681ea..8fe4824378 100644 --- a/docs/guides/contribute/navigation.md +++ b/docs/guides/contribute/navigation.md @@ -17,37 +17,37 @@ When the documentation project started, it was hoped that menus in Mkdocs would Our goals were: -* Create the folder structure as needed now (new folders may be required in the future) -* Adjust the navigation so that the Rocky Installation, Migration, and Contribution areas were at the top -* Adjust the navigation to name some folders better, and enable correct capitalization. As an example, "DNS" and "File Sharing Services" otherwise show up as "Dns" and "File sharing" without some manipulation. -* Ensure that these navigation files are restricted to Managers and Editors +- Create the folder structure as needed now (new folders may be required in the future) +- Adjust the navigation so that the Rocky Installation, Migration, and Contribution areas were at the top +- Adjust the navigation to name some folders better, and enable correct capitalization. As an example, "DNS" and "File Sharing Services" otherwise show up as "Dns" and "File sharing" without some manipulation. +- Ensure that these navigation files are restricted to Managers and Editors This last item may seem unnecessary to some reading this, but it will become more apparent as this document continues. ## Assumptions -The assumption is that you have a local clone of the Rocky GitHub repository: [https://github.com/rocky-linux/documentation](https://github.com/rocky-linux/documentation). +The assumption is that you have a local clone of the Rocky GitHub repository: . ## Environment changes -With these changes comes a real need to "see" how any changes you are making affect content, in the context of the website, _BEFORE_ that content is committed to the document repository, and subsequently goes 'live'. +With these changes comes a real need to "see" how any changes you are making affect content, in the context of the website, *BEFORE* that content is committed to the document repository, and subsequently goes 'live'. MkDocs is a [Python](https://www.python.org) application and the extra packages it uses are also Python code, this means that the environment required to run MkDocs needs to be a **correctly configured Python environment**. Setting up Python for development tasks (which is what is being done running MkDocs) is not a trivial task, and instructions for that are out of the scope of this document. Some considerations are: -* The version of Python should be >= 3.8, also **particular care must be taken not to use the 'system' Python version of a computer if the computer runs Linux/macOS**. For example, as of the writing of this document, the system version of Python on macOS is still version 2.7. -* Running a Python 'virtual environment'. When running Python application project and installing packages, for example MkDocs, it is **strongly recommended** by the Python community to [create an isolated virtual environment](https://realpython.com/python-virtual-environments-a-primer/) for each project. -* Use a modern IDE (Integrated Development Environment) that supports Python well. Two popular IDEs, which also have integrated support for running virtual environments, are: - * PyCharm - (free version available) the leading IDE for Python https://www.jetbrains.com/pycharm/ - * Visual Studio Code - (free version available) from Microsoft https://code.visualstudio.com +- The version of Python should be >= 3.8, also **particular care must be taken not to use the 'system' Python version of a computer if the computer runs Linux/macOS**. For example, as of the writing of this document, the system version of Python on macOS is still version 2.7. +- Running a Python 'virtual environment'. When running Python application project and installing packages, for example MkDocs, it is **strongly recommended** by the Python community to [create an isolated virtual environment](https://realpython.com/python-virtual-environments-a-primer/) for each project. +- Use a modern IDE (Integrated Development Environment) that supports Python well. Two popular IDEs, which also have integrated support for running virtual environments, are: + - PyCharm - (free version available) the leading IDE for Python + - Visual Studio Code - (free version available) from Microsoft Doing this effectively requires: -* Setting up a new Python project which, ideally, uses a virtual environment (above). -* Installing `mkdocs` -* Installing some python plugins -* Cloning this Rocky GitHub repository:[https://github.com/rocky-linux/docs.rockylinux.org](https://github.com/rocky-linux/docs.rockylinux.org) -* Linking to the `docs` folder within your cloned documentation repository (you can also just modify the mkdocs.yml file if you wish to load the correct folder, but linking keeps your mkdocs environment cleaner) -* Running `mkdocs serve` within your clone of docs.rockylinux.org +- Setting up a new Python project which, ideally, uses a virtual environment (above). +- Installing `mkdocs` +- Installing some python plugins +- Cloning this Rocky GitHub repository: +- Linking to the `docs` folder within your cloned documentation repository (you can also just modify the mkdocs.yml file if you wish to load the correct folder, but linking keeps your mkdocs environment cleaner) +- Running `mkdocs serve` within your clone of docs.rockylinux.org !!! tip @@ -59,9 +59,9 @@ Doing this effectively requires: ### Installing -* Install `mkdocs` with the python environment: `pip install mkdocs` -* Install needed plugins: `pip install mkdocs-material mkdocs-localsearch mkdocs-awesome-pages-plugin mkdocs-redirects mkdocs-i18n` -* Clone the repository (noted above) +- Install `mkdocs` with the python environment: `pip install mkdocs` +- Install needed plugins: `pip install mkdocs-material mkdocs-localsearch mkdocs-awesome-pages-plugin mkdocs-redirects mkdocs-i18n` +- Clone the repository (noted above) ### Linking and running `mkdocs` @@ -71,22 +71,21 @@ Inside your docs.rockylinux.org local (clone), do the following. This assumes th Again, if you desire, you can modify the local copy of the `mkdocs.yml` file to set the path. If using this method, you would modify this line to point to your `documentation/docs` folder: -``` +```text docs_dir: 'docs/docs' ``` -Once completed, you can try running `mkdocs serve` to see if you get your desired content. This will run on your localhost on port 8000; for example: http://127.0.0.1:8000/ +Once completed, you can try running `mkdocs serve` to see if you get your desired content. This will run on your localhost on port 8000; for example: ## Navigation and other changes Navigation is handled with mkdocs `.pages` files **OR** by the value of the "title:" meta in the document front matter. The `.pages` files are not terribly complex, BUT, if something is left out, it can cause the server to fail to load. That's why this procedure is **ONLY** for Managers and Editors. These individuals are going to have the tools in place (local install of mkdocs, plus clones of both documentation and docs.rockylinux.org) so that something pushed and merged to GitHub will not break the serving of the documentation website. A contributor cannot be expected to have even one of these requirements. - ### `.pages` files As already stated, the `.pages` files are generally pretty simple. They are a YAML formatted file that `mkdocs` reads before rendering the content. To take a look at one of the more complex `.pages` files, let's look at the one created to help format the side navigation: -``` +```yaml --- nav: - ... | index*.md @@ -109,16 +108,18 @@ nav: - Network: network - Package Management: package_management - ... - ``` -Here, the `index*md` shows the "Guides Home: ", `installation*.md` shows the "Installing Rocky Linux" document link, and the `migrate2rocky*.md` shows the "Migrating To Rocky Linux" document link. The "*" within each link allows that document to be in _any_ language. Finally, by placing "Contribute" next, it falls beneath these items rather than in the normal (alphabetic) sort order. Looking down the list, you can see what each item is doing. Note that after the "Package Management: package_management" entry, there are actually two more folders (security and web). These do not require any additional formatting, so we are just telling `mkdocs` to load them normally with the "-..." + +Here, the `index*md` shows the "Guides Home: ", `installation*.md` shows the "Installing Rocky Linux" document link, and the `migrate2rocky*.md` shows the "Migrating To Rocky Linux" document link. The "*" within each link allows that document to be in *any* language. Finally, by placing "Contribute" next, it falls beneath these items rather than in the normal (alphabetic) sort order. Looking down the list, you can see what each item is doing. Note that after the "Package Management: package_management" entry, there are actually two more folders (security and web). These do not require any additional formatting, so we are just telling `mkdocs` to load them normally with the "-..." You can also use YAML formatting within an actual file. A reason for doing this might be that the beginning heading of the file is so long, that it just doesn't display well in the navigation section. As an example, take this document heading "# `mod_ssl` on Rocky Linux in an httpd Apache Web-Server Environment". That is very long. It displays very poorly in the side navigation once the "Web" navigation item is opened. To fix this, you can either work with the author to change his heading, or, you can change how it displays in the menu by adding a title before the heading inside the document. For the example document, there is a title added: -``` + +```text --- title: Apache With `mod_ssl` --- ``` + This changes the title regarding the navigation but leaves the author's original title in place within the document. There will probably not be a lot of need for additional `.pages` files. They should be used economically. diff --git a/docs/guides/contribute/style_guide.md b/docs/guides/contribute/style_guide.md index a5840a83ea..b60177c852 100644 --- a/docs/guides/contribute/style_guide.md +++ b/docs/guides/contribute/style_guide.md @@ -19,16 +19,16 @@ tags: This guide outlines English-language style standards to **improve readability, highlight special cases,** and **enhance translation work** across Rocky Linux documentation. For style questions not addressed in this guide, please refer to the following: -* [Merriam Webster Dictionary](https://www.merriam-webster.com/) -* [Chicago Manual of Style (CMOS), 17th ed.](https://www.chicagomanualofstyle.org/home.html) +- [Merriam Webster Dictionary](https://www.merriam-webster.com/) +- [Chicago Manual of Style (CMOS), 17th ed.](https://www.chicagomanualofstyle.org/home.html) ### Contributing For a more complete understanding of contributing, please consult our related guides: -* [Rocky Linux Contribution Guide](https://docs.rockylinux.org/guides/contribute/) for system and software requirements for getting started. -* [Rocky Linux First Time Contributors Guide](beginners.md) for an orientation to GitHub, our documentation home base. -* [Rocky Docs Formatting](rockydocs_formatting.md) for Markdown structure. +- [Rocky Linux Contribution Guide](https://docs.rockylinux.org/guides/contribute/) for system and software requirements for getting started. +- [Rocky Linux First Time Contributors Guide](beginners.md) for an orientation to GitHub, our documentation home base. +- [Rocky Docs Formatting](rockydocs_formatting.md) for Markdown structure. ## Style Guidelines @@ -38,31 +38,31 @@ For a more complete understanding of contributing, please consult our related gu **Distinctives for technical writing** as outlined in the Chicago Manual of Style include the following: -* Double quotation marks (“Chicago style”) rather than single quotation marks (‘Oxford style’). -* Periods and commas go inside quotation marks “like this,” rather than “like this”. -* The em dash {shift}+{option}+{-} has no spaces before or after—like this—and is preferred for parenthetical phrases. -* Use a serial comma before the “and” in a list of three items: “Peas, mustard, and carrots.” -* Headings should be generally made in headline-style capitalization: Capitalize the first and last words, as well as all nouns, pronouns, verbs, and adverbs. If your document works better with sentence-style capitalization, perhaps because you frequently reference acronyms, make it consistent within the entire document. -* Headings do not need a period or semicolon at the end, even with sentence-style capitalization, unless ending in an abbreviation. -* Bulleted and numbered lists: Avoid beginning capitalization or ending punctuation, unless the item is a complete sentence. +- Double quotation marks (“Chicago style”) rather than single quotation marks (‘Oxford style’). +- Periods and commas go inside quotation marks “like this,” rather than “like this”. +- The em dash {shift}+{option}+{-} has no spaces before or after—like this—and is preferred for parenthetical phrases. +- Use a serial comma before the “and” in a list of three items: “Peas, mustard, and carrots.” +- Headings should be generally made in headline-style capitalization: Capitalize the first and last words, as well as all nouns, pronouns, verbs, and adverbs. If your document works better with sentence-style capitalization, perhaps because you frequently reference acronyms, make it consistent within the entire document. +- Headings do not need a period or semicolon at the end, even with sentence-style capitalization, unless ending in an abbreviation. +- Bulleted and numbered lists: Avoid beginning capitalization or ending punctuation, unless the item is a complete sentence. ### Voice and Tone -* **Plain language.** This can be described as a *less-conversational* style. Most of our documentation fits within this standard. - * Avoid metaphors and idioms. - * Say what you mean in as few words as possible. - * Identify and avoid unnecessarily technical terms. Consider that your audience is mostly people who have some familiarity with the subject matter, but may not be subject-matter experts. - * Exceptions to plain language: - * A more conversational style is appropriate for documentation addressed to newcomers or beginners or for writing content like blog posts. - * A more formal or terse wording style is appropriate for documentation addressed to advanced users or API (Application Programming Interface) documentation. -* **Inclusive language.** - * Language use evolves over time. Certain words have evolved to carry negative connotations so documentation should be rewritten to use new words. - * *Master/slave* becomes *primary/secondary* or an agreed upon organizational standard. - * *Blacklist/whitelist* becomes *blocklist/allowlist* or an agreed upon organizational standard. - * You may think of other relevant examples as you create documentation. - * When speaking of a person of *unknown* or *non-binary* gender, it is now considered acceptable to use “they” as a singular pronoun. - * When speaking of one’s capabilities, frame answers as *abilities* rather than *limitations.* For example, if you are wondering whether we have documentation about running Steam on Rocky Linux, the answer is not just “no.” Rather, “Sounds like that’s a great place for you to create something to add to our tree!” -* **Avoid contractions.** This assists with translation efforts. The exception to this is when writing something in a more conversational tone, such as blog posts or welcome instructions for new community members. +- **Plain language.** This can be described as a *less-conversational* style. Most of our documentation fits within this standard. + - Avoid metaphors and idioms. + - Say what you mean in as few words as possible. + - Identify and avoid unnecessarily technical terms. Consider that your audience is mostly people who have some familiarity with the subject matter, but may not be subject-matter experts. + - Exceptions to plain language: + - A more conversational style is appropriate for documentation addressed to newcomers or beginners or for writing content like blog posts. + - A more formal or terse wording style is appropriate for documentation addressed to advanced users or API (Application Programming Interface) documentation. +- **Inclusive language.** + - Language use evolves over time. Certain words have evolved to carry negative connotations so documentation should be rewritten to use new words. + - *Master/slave* becomes *primary/secondary* or an agreed upon organizational standard. + - *Blacklist/whitelist* becomes *blocklist/allowlist* or an agreed upon organizational standard. + - You may think of other relevant examples as you create documentation. + - When speaking of a person of *unknown* or *non-binary* gender, it is now considered acceptable to use “they” as a singular pronoun. + - When speaking of one’s capabilities, frame answers as *abilities* rather than *limitations.* For example, if you are wondering whether we have documentation about running Steam on Rocky Linux, the answer is not just “no.” Rather, “Sounds like that’s a great place for you to create something to add to our tree!” +- **Avoid contractions.** This assists with translation efforts. The exception to this is when writing something in a more conversational tone, such as blog posts or welcome instructions for new community members. ## Formatting @@ -74,16 +74,16 @@ When possible use the name of the month in the format {day} {Month} {year}. Howe If you have a procedure with only one step, use a bullet rather than a number. For example: -* Implement this idea and move on. +- Implement this idea and move on. ### Graphical Interface Language -* Text instructions regarding a UI: When describing a command to be entered into a user interface, use the word “enter” rather than “put” or “type.” Use a codeblock to write out the command (i.e., set it off with backticks): +- Text instructions regarding a UI: When describing a command to be entered into a user interface, use the word “enter” rather than “put” or “type.” Use a codeblock to write out the command (i.e., set it off with backticks): *Example Markdown text* `In the **commit message** box, enter update_thisdoc.` -* Names of UI elements: **Bold** names of UI elements such as buttons, menu items, names of dialog boxes, and more, even if the word will not be clickable: +- Names of UI elements: **Bold** names of UI elements such as buttons, menu items, names of dialog boxes, and more, even if the word will not be clickable: *Example Markdown text* `In the **Format** menu, click **Line Spacing**.` @@ -92,11 +92,11 @@ If you have a procedure with only one step, use a bullet rather than a number. F ### Starting content of each guide, or page/chapter of a book -* **Abstract.** A brief statement of what to expect from this page -* **Objectives.** A bulleted list of what this page will convey to the reader -* **Skills** required/learned. -* **Difficulty level.** 1 star for easy, 2 for intermediate, etc. -* **Reading time.** Divide the number of words in your document by a reading rate of 75 words per minute to determine this number. +- **Abstract.** A brief statement of what to expect from this page +- **Objectives.** A bulleted list of what this page will convey to the reader +- **Skills** required/learned. +- **Difficulty level.** 1 star for easy, 2 for intermediate, etc. +- **Reading time.** Divide the number of words in your document by a reading rate of 75 words per minute to determine this number. ### Admonitions @@ -108,32 +108,32 @@ Within Markdown, admonitions are a way to put information into a box to highligh ### Images -* Provide text descriptions in alt-text or captions for every non-text item such as diagrams, images, or icons. -* Avoid screenshots of text when possible. -* Make alt-text meaningful, not just descriptive. For action icons, for example, enter a description of the function rather than a description of its appearance. +- Provide text descriptions in alt-text or captions for every non-text item such as diagrams, images, or icons. +- Avoid screenshots of text when possible. +- Make alt-text meaningful, not just descriptive. For action icons, for example, enter a description of the function rather than a description of its appearance. ### Links -* Make links descriptive, so it is obvious where they will lead from the text or context. Avoid hyperlinks with names like “click here.” -* Verify that all links work as described. +- Make links descriptive, so it is obvious where they will lead from the text or context. Avoid hyperlinks with names like “click here.” +- Verify that all links work as described. ### Tables -* Create tables with a logical order left to right, top to bottom. -* Avoid blank cells at the top or left of the table. -* Avoid merged cells that span multiple columns. +- Create tables with a logical order left to right, top to bottom. +- Avoid blank cells at the top or left of the table. +- Avoid merged cells that span multiple columns. ### Colors -* Some elements in Markdown, such as admonitions, have an assigned color to assist with visual comprehension. In general they also have an assigned name; for example, the “danger” admonition displays a red box but also has the descriptor “danger” built into the description. But when creating a custom admonition, be aware that color cannot be the only means of communicating a command or level of warning. -* Any command that includes a sensory direction, such as *above* or *below*, *color*, *size*, *visual location* on the page, etc., should also include a direction that is communicable by only text description. -* When creating a graphical element, ensure that there is enough contrast between the foreground and background colors to be easy for a screen reader to interpret. +- Some elements in Markdown, such as admonitions, have an assigned color to assist with visual comprehension. In general they also have an assigned name; for example, the “danger” admonition displays a red box but also has the descriptor “danger” built into the description. But when creating a custom admonition, be aware that color cannot be the only means of communicating a command or level of warning. +- Any command that includes a sensory direction, such as *above* or *below*, *color*, *size*, *visual location* on the page, etc., should also include a direction that is communicable by only text description. +- When creating a graphical element, ensure that there is enough contrast between the foreground and background colors to be easy for a screen reader to interpret. ### Headings -* Use all levels of headings without skipping any levels. -* Nest all material under headings to aid in readability. -* Remember that in Markdown only one Level One heading may be used. +- Use all levels of headings without skipping any levels. +- Nest all material under headings to aid in readability. +- Remember that in Markdown only one Level One heading may be used. ## Summary