From 7069d7e0b04e1577cf659f5c376425519b72a532 Mon Sep 17 00:00:00 2001 From: smishra <8684346+HackersSpirit@users.noreply.github.com> Date: Fri, 3 Oct 2025 11:27:08 +1000 Subject: [PATCH] Standardize Markdown formatting across documentation #271 --- contributing/CONTRIBUTING.md | 2 + contributing/markdown-style-guide.md | 70 +++++++++++++++++++ .../getting-practical.md | 14 ++-- docs/intro-to-oss/tools-to-be-successful.md | 18 ++--- 4 files changed, 88 insertions(+), 16 deletions(-) create mode 100644 contributing/markdown-style-guide.md diff --git a/contributing/CONTRIBUTING.md b/contributing/CONTRIBUTING.md index eb87ddac..66fa75aa 100644 --- a/contributing/CONTRIBUTING.md +++ b/contributing/CONTRIBUTING.md @@ -33,6 +33,8 @@ We actively welcome your PRs. However, before working on changes, you must ensur 2. Run and check your changes locally. Ensure that everything works as it should. +3. Follow the [Markdown Style Guide](./markdown-style-guide.md) for consistent formatting in documentation changes. + ### Submitting a PR Template 1. Ensure that you address one issue in one PR.
If you work on multiple issues, work on them separately and create one PR to address each issue. diff --git a/contributing/markdown-style-guide.md b/contributing/markdown-style-guide.md new file mode 100644 index 00000000..68e81088 --- /dev/null +++ b/contributing/markdown-style-guide.md @@ -0,0 +1,70 @@ +# Markdown Style Guide + +This guide outlines the standards for Markdown formatting in this repository to ensure consistency, readability, and maintainability. + +## Headings + +- Use ATX-style headings: `#` for level 1, `##` for level 2, etc. +- Always include a space after the `#`. +- Example: + ``` + # Main Title + ## Subsection + ``` + +## Lists + +- Use `-` for unordered lists. +- Use `1. 2.` for ordered lists. +- Indent sublists with 2 spaces. +- Example: + ``` + - Item 1 + - Subitem + 1. First + 2. Second + ``` + +## Code Blocks + +- Use fenced code blocks with triple backticks (```). +- Specify the language for syntax highlighting when possible. +- Do not indent top-level code blocks. +- For code blocks inside list items, indent the entire block with 4 spaces. +- Example: + ``` + ```bash + echo "Hello" + ``` + ``` + +## Links + +- Use inline link style: `[text](url)` +- Example: `[Open Source](https://opensource.org/)` + +## Emphasis + +- Use `**text**` for bold. +- Use `*text*` for italic. +- Use `` `text` `` for inline code. + +## Images + +- Use `![alt text](path/to/image.png)` + +## Tables + +- Use Markdown table syntax with pipes and dashes. +- Example: + ``` + | Header 1 | Header 2 | + |----------|----------| + | Cell 1 | Cell 2 | + ``` + +## Miscellaneous + +- Use consistent spacing and indentation throughout. +- Avoid trailing spaces. +- Use blank lines to separate sections for readability. diff --git a/docs/becoming-a-maintainer/getting-practical.md b/docs/becoming-a-maintainer/getting-practical.md index 6f05cf9e..b0ef7397 100644 --- a/docs/becoming-a-maintainer/getting-practical.md +++ b/docs/becoming-a-maintainer/getting-practical.md @@ -337,13 +337,13 @@ body: - Select the type of issue you want to create. In this example, we'll select Feature Request. - Write your issue. If you're following along the example, we'll write a feature request for a new resource: - ```markdown - **Type of feature:** 🍕 Feature - **Current behavior:** I'd like to see a new resource for #100DaysOfOSS. - **Suggested solution:** Add a new resource that introduces people to open source through [#100DaysOfOSS](https://opensauced.pizza/docs/community/100-days-of-oss/). - **Code of Conduct:** I agree to follow this project's Code of Conduct. - **Contributing Docs:** I agree to follow this project's Contribution Docs. - ``` + ```markdown + **Type of feature:** 🍕 Feature + **Current behavior:** I'd like to see a new resource for #100DaysOfOSS. + **Suggested solution:** Add a new resource that introduces people to open source through [#100DaysOfOSS](https://opensauced.pizza/docs/community/100-days-of-oss/). + **Code of Conduct:** I agree to follow this project's Code of Conduct. + **Contributing Docs:** I agree to follow this project's Contribution Docs. + ``` - Once you've completed the issues, click "Submit new issue." diff --git a/docs/intro-to-oss/tools-to-be-successful.md b/docs/intro-to-oss/tools-to-be-successful.md index 3b642622..1bb2173b 100644 --- a/docs/intro-to-oss/tools-to-be-successful.md +++ b/docs/intro-to-oss/tools-to-be-successful.md @@ -49,12 +49,12 @@ To get started with Git and GitHub, follow these steps: 2. **Configure Git**: After installing Git, open a terminal or command prompt and configure your Git user information by running the following commands: - ```bash - git config --global user.name "Your Name" - git config --global user.email "your.email@example.com" - ``` + ```bash + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + ``` - Replace `Your Name` with your full name and `your.email@example.com` with the email address you used to sign up for GitHub. + Replace `Your Name` with your full name and `your.email@example.com` with the email address you used to sign up for GitHub. #### Practicing Contributing with VS Code @@ -72,11 +72,11 @@ To practice using GitHub, we're going to walk through creating a repository, clo 2. **Clone the repository**: Once you have created a new repository, you can clone it to your local machine by running the following command in your terminal or command prompt: - ```bash - git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git - ``` + ```bash + git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git + ``` - Replace "YOUR-USERNAME" with your GitHub username and "REPOSITORY-NAME" with `practice-repository`. + Replace "YOUR-USERNAME" with your GitHub username and "REPOSITORY-NAME" with `practice-repository`. 3. **Access your repository in your code editor**: For this example, we're using VS Code. Open VS Code, navigate to the file tab, and then open your `practice-repository`.