From 79ba54959e470075fff88ed7e646f78dd2310ff0 Mon Sep 17 00:00:00 2001 From: Ikechukwu Uchendu Date: Sun, 19 Nov 2023 11:00:48 -0500 Subject: [PATCH] Added GitHub action to lint markdown files. Fixes #55. --- .github/workflows/markdown_linter.yml | 35 +++ .../markdown_linter/.mdlintconfig.yml | 266 ++++++++++++++++++ .../workflows/markdown_linter/.mdlintignore | 7 + README.md | 38 ++- conventions.md | 64 +++-- 5 files changed, 382 insertions(+), 28 deletions(-) create mode 100644 .github/workflows/markdown_linter.yml create mode 100644 .github/workflows/markdown_linter/.mdlintconfig.yml create mode 100644 .github/workflows/markdown_linter/.mdlintignore diff --git a/.github/workflows/markdown_linter.yml b/.github/workflows/markdown_linter.yml new file mode 100644 index 00000000..fb9641c7 --- /dev/null +++ b/.github/workflows/markdown_linter.yml @@ -0,0 +1,35 @@ +name: Linting Quarto Markdown files +on: + push: + pull_request: + +jobs: + lint-qmd-files: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Installing GitHub CLI + run: | + sudo apt install -y gh jq nodejs npm + + + - name: Installing Markdown Linter + run: | + sudo npm install -g markdownlint-cli + + - name: Markdown linting job has been triggered + run: | + echo "The job was automatically triggered by a ${{ github.event_name }} event." + + - name: Running markdown linter + run: | + markdownlint --config .github/workflows/markdown_linter/.mdlintconfig.yml --ignore-path .github/workflows/markdown_linter/.mdlintignore ./ + ret=$? + if [ $ret -eq 1 ]; then + echo "Linting failed. Please correct any errors and run the job again." + exit 1 + fi \ No newline at end of file diff --git a/.github/workflows/markdown_linter/.mdlintconfig.yml b/.github/workflows/markdown_linter/.mdlintconfig.yml new file mode 100644 index 00000000..9ed401bf --- /dev/null +++ b/.github/workflows/markdown_linter/.mdlintconfig.yml @@ -0,0 +1,266 @@ +# Example markdownlint configuration with all properties set to their default value + +# Default state for all rules +default: true + +# Path to configuration file to extend +extends: null + +# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md001.md +MD001: true + +# MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md003.md +MD003: + # Heading style + style: "consistent" + +# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md004.md +MD004: + # List style + style: "consistent" + +# MD005/list-indent : Inconsistent indentation for list items at the same level : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md005.md +MD005: true + +# MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md007.md +MD007: + # Spaces for indent + indent: 4 + # Whether to indent the first level of the list + start_indented: false + # Spaces for first level indent (when start_indented is set) + start_indent: 4 + +# MD009/no-trailing-spaces : Trailing spaces : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md009.md +MD009: + # Spaces for line break + br_spaces: 2 + # Allow spaces for empty lines in list items + list_item_empty_lines: false + # Include unnecessary breaks + strict: false + +# MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md010.md +MD010: + # Include code blocks + code_blocks: true + # Fenced code languages to ignore + ignore_code_languages: [] + # Number of spaces for each hard tab + spaces_per_tab: 4 + +# MD011/no-reversed-links : Reversed link syntax : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md011.md +MD011: true + +# MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md012.md +MD012: + # Consecutive blank lines + maximum: 1 + +# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md013.md +MD013: + # Number of characters + line_length: 80 + # Number of characters for headings + heading_line_length: 80 + # Number of characters for code blocks + code_block_line_length: 80 + # Include code blocks + code_blocks: true + # Include tables + tables: true + # Include headings + headings: true + # Strict length checking + strict: false + # Stern length checking + stern: false + +# MD014/commands-show-output : Dollar signs used before commands without showing output : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md014.md +MD014: true + +# MD018/no-missing-space-atx : No space after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md018.md +MD018: true + +# MD019/no-multiple-space-atx : Multiple spaces after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md019.md +MD019: true + +# MD020/no-missing-space-closed-atx : No space inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md020.md +MD020: true + +# MD021/no-multiple-space-closed-atx : Multiple spaces inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md021.md +MD021: true + +# MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md022.md +MD022: + # Blank lines above heading + lines_above: 1 + # Blank lines below heading + lines_below: 1 + +# MD023/heading-start-left : Headings must start at the beginning of the line : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md023.md +MD023: true + +# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md024.md +MD024: + # Only check sibling headings + allow_different_nesting: true + # Only check sibling headings + siblings_only: false + +# MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md025.md +MD025: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD026/no-trailing-punctuation : Trailing punctuation in heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md026.md +MD026: + # Punctuation characters + punctuation: ".,;:!。，；：！" + +# MD027/no-multiple-space-blockquote : Multiple spaces after blockquote symbol : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md027.md +MD027: true + +# MD028/no-blanks-blockquote : Blank line inside blockquote : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md028.md +MD028: true + +# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md029.md +MD029: + # List style + style: "one_or_ordered" + +# MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md030.md +MD030: + # Spaces for single-line unordered list items + ul_single: 1 + # Spaces for single-line ordered list items + ol_single: 1 + # Spaces for multi-line unordered list items + ul_multi: 1 + # Spaces for multi-line ordered list items + ol_multi: 1 + +# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md031.md +MD031: + # Include list items + list_items: true + +# MD032/blanks-around-lists : Lists should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md032.md +MD032: true + +# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md033.md +# MD033: + # Allowed elements + # allowed_elements: [] + +# MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md034.md +MD034: true + +# MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md035.md +MD035: + # Horizontal rule style + style: "consistent" + +# MD036/no-emphasis-as-heading : Emphasis used instead of a heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md036.md +MD036: + # Punctuation characters + punctuation: ".,;:!?。，；：！？" + +# MD037/no-space-in-emphasis : Spaces inside emphasis markers : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md037.md +MD037: true + +# MD038/no-space-in-code : Spaces inside code span elements : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md038.md +MD038: true + +# MD039/no-space-in-links : Spaces inside link text : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md039.md +MD039: true + +# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md040.md +MD040: + # List of languages + allowed_languages: [] + # Require language only + language_only: false + +# MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md041.md +MD041: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md042.md +MD042: true + +# MD043/required-headings : Required heading structure : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md043.md +MD043: + # List of headings + headings: ["*"] + # Match case of headings + match_case: false + +# MD044/proper-names : Proper names should have the correct capitalization : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md044.md +MD044: + # List of proper names + names: [] + # Include code blocks + code_blocks: true + # Include HTML elements + html_elements: true + +# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md045.md +MD045: true + +# MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md046.md +MD046: + # Block style + style: "consistent" + +# MD047/single-trailing-newline : Files should end with a single newline character : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md047.md +MD047: true + +# MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md048.md +MD048: + # Code fence style + style: "consistent" + +# MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md049.md +MD049: + # Emphasis style + style: "consistent" + +# MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md050.md +MD050: + # Strong style + style: "consistent" + +# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md051.md +MD051: true + +# MD052/reference-links-images : Reference links and images should use a label that is defined : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md052.md +MD052: + # Include shortcut syntax + shortcut_syntax: false + +# MD053/link-image-reference-definitions : Link and image reference definitions should be needed : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md053.md +MD053: + # Ignored definitions + ignored_definitions: + - "//" + +# MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md054.md +MD054: + # Allow autolinks + autolink: true + # Allow inline links and images + inline: true + # Allow full reference links and images + full: true + # Allow collapsed reference links and images + collapsed: true + # Allow shortcut reference links and images + shortcut: true + # Allow URLs as inline links + url_inline: true \ No newline at end of file diff --git a/.github/workflows/markdown_linter/.mdlintignore b/.github/workflows/markdown_linter/.mdlintignore new file mode 100644 index 00000000..9273b73d --- /dev/null +++ b/.github/workflows/markdown_linter/.mdlintignore @@ -0,0 +1,7 @@ +_book/* +.github +.quarto +*.yml +*.html +*.png +*.json \ No newline at end of file diff --git a/README.md b/README.md index 0e4ab325..04adfaf5 100644 --- a/README.md +++ b/README.md @@ -2,55 +2,69 @@ [![All Contributors](https://img.shields.io/github/all-contributors/harvard-edge/cs249r_book?color=ee8449&style=flat-square)](#contributors) -Welcome to the collaborative book repository for students of CS249r: Tiny Machine Learning at Harvard! This repository -contains the source files of chapters and sections written by your peers. We're excited to see your contributions! +Welcome to the collaborative book repository for students of CS249r: Tiny +Machine Learning at Harvard! This repository contains the source files +of chapters and sections written by your peers. We're excited to see your +contributions! ## Contributing To contribute to the repository using pull requests, follow these steps: 1. **Fork the Repository**: - - Navigate to the repository's GitHub page and click the 'Fork' button at the top-right corner. + + - Navigate to the repository's GitHub page and click the 'Fork' button at + the top-right corner. 2. **Clone Your Forked Repository**: + ```bash git clone https://github.com/YOUR_USERNAME/cs249r_book.git ``` 3. **Navigate to the Repository**: + ```bash cd cs249r_book ``` 4. **Set Upstream Remote**: + ```bash git remote add upstream https://github.com/harvard-edge/cs249r_book.git ``` 5. **Create a New Branch** for your chapter/section: + ```bash git checkout -b name-of-your-new-branch ``` -6. **Make your edits** for your chapter or section in [Markdown](https://quarto.org/docs/authoring/markdown-basics.html). +6. **Make your edits** for your chapter or section + in [Markdown](https://quarto.org/docs/authoring/markdown-basics.html). 7. **Commit Changes to Your Branch**: + ```bash git add . git commit -m "Briefly describe your changes" ``` 8. **Push Your Branch to Your Forked Repository**: + ```bash git push origin name-of-your-new-branch ``` -9. Navigate to your fork on GitHub and click the 'New pull request' button. Ensure you're comparing your branch from - your fork to the `main` branch of the original `harvard-edge/cs249r_book` repository. +9. Navigate to your fork on GitHub and click the 'New pull request' button. + Ensure you're comparing your branch from + your fork to the `main` branch of the original `harvard-edge/cs249r_book` + repository. 10. Submit the pull request with a descriptive message. -The instructors will assess your pull request and provide feedback. Once it's approved, your contribution will be +The instructors will assess your pull request and provide feedback. Once it's +approved, your contribution will be integrated into the `main` branch, and the book's website will be updated. For a more detailed guide on the CS249r documentation process and peer review, @@ -60,7 +74,8 @@ check [here](https://docs.google.com/document/d/1izDoWwFLnV8XK2FYCl23_9KYL_7EQ5O ## Website -The book's website is automatically constructed from the `gh-pages` branch. Once reviewed, changes to `main` are merged +The book's website is automatically constructed from the `gh-pages` branch. Once +reviewed, changes to `main` are merged into `gh-pages`. You can view the book's website @@ -70,7 +85,9 @@ at: [https://harvard-edge.github.io/cs249r_book/](https://harvard-edge.github.io ## Local Rendering -You need to have `quarto` installed for local rendering of the book. Please follow the [Quarto installation instructions here](https://quarto.org/docs/download/). +You need to have `quarto` installed for local rendering of the book. Please +follow +the [Quarto installation instructions here](https://quarto.org/docs/download/). Once that's done, the following command can be used to produce the HTML pages: @@ -140,5 +157,6 @@ quarto render -This project follows the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are +This project follows the [all-contributors](https://allcontributors.org) +specification. Contributions of any kind are welcome! diff --git a/conventions.md b/conventions.md index 9afe1507..55d14716 100644 --- a/conventions.md +++ b/conventions.md @@ -3,38 +3,66 @@ Please follow these conventions as you contribute to this online book: 1. **Clear Structure and Organization**: - - **Chapter Outlines**: Begin each chapter with an outline that provides an overview of the topics covered. - - **Sequential Numbering**: Utilize sequential numbering for chapters, sections, and subsections to facilitate easy reference. + + - **Chapter Outlines**: Begin each chapter with an outline that provides an + overview of the topics covered. + - **Sequential Numbering**: Utilize sequential numbering for chapters, + sections, and subsections to facilitate easy reference. 2. **Accessible Language**: - - **Glossary**: Include a glossary that defines technical terms and jargon. - - **Consistent Terminology**: Maintain consistent use of terminology throughout the book to avoid confusion. + + - **Glossary**: Include a glossary that defines technical terms and jargon. + - **Consistent Terminology**: Maintain consistent use of terminology + throughout the book to avoid confusion. 3. **Learning Aids**: - - **Diagrams and Figures**: Employ diagrams, figures, and tables to visually convey complex concepts. - - **Sidebars**: Use sidebars for additional information, anecdotes, or to provide real-world context to the theoretical content. + + - **Diagrams and Figures**: Employ diagrams, figures, and tables to visually + convey complex concepts. + - **Sidebars**: Use sidebars for additional information, anecdotes, or to + provide real-world context to the theoretical content. 4. **Interactive Elements**: - - **Exercises and Projects**: Integrate exercises and projects at the end of each chapter to encourage active learning and practical application of concepts. - - **Case Studies**: Incorporate case studies to provide a deeper understanding of how principles are applied in real-world situations. + + - **Exercises and Projects**: Integrate exercises and projects at the end of + each chapter to encourage active learning and practical application of + concepts. + - **Case Studies**: Incorporate case studies to provide a deeper + understanding of how principles are applied in real-world situations. 5. **References and Further Reading**: - - **Bibliography**: Include a bibliography at the end of each chapter for readers who wish to delve deeper into specific topics. - - **Citations**: Maintain a consistent style for citations, adhering to recognized academic standards like APA, MLA, or Chicago. + + - **Bibliography**: Include a bibliography at the end of each chapter for + readers who wish to delve deeper into specific topics. + - **Citations**: Maintain a consistent style for citations, adhering to + recognized academic standards like APA, MLA, or Chicago. 6. **Supporting Materials**: - - **Supplementary Online Resources**: Provide links to supplementary online resources, such as video lectures, webinars, or interactive modules. - - **Datasets and Code Repositories**: Share datasets and code repositories for hands-on practice, particularly for sections dealing with algorithms and applications. + + - **Supplementary Online Resources**: Provide links to supplementary online + resources, such as video lectures, webinars, or interactive modules. + - **Datasets and Code Repositories**: Share datasets and code repositories + for hands-on practice, particularly for sections dealing with algorithms + and applications. 7. **Feedback and Community Engagement**: - - **Forums and Discussion Groups**: Establish forums or discussion groups where readers can interact, ask questions, and share knowledge. - - **Open Review Process**: Implement an open review process, inviting feedback from the community to continuously improve the content. + + - **Forums and Discussion Groups**: Establish forums or discussion groups + where readers can interact, ask questions, and share knowledge. + - **Open Review Process**: Implement an open review process, inviting + feedback from the community to continuously improve the content. 8. **Inclusivity and Accessibility**: - - **Inclusive Language**: Utilize inclusive language that respects diversity and promotes equality. - - **Accessible Formats**: Ensure the textbook is available in accessible formats, including audio and Braille, to cater to readers with disabilities. + + - **Inclusive Language**: Utilize inclusive language that respects diversity + and promotes equality. + - **Accessible Formats**: Ensure the textbook is available in accessible + formats, including audio and Braille, to cater to readers with + disabilities. 9. **Index**: - - **Comprehensive Index**: Include a comprehensive index at the end of the book to help readers quickly locate specific information. + - **Comprehensive Index**: Include a comprehensive index at the end of the + book to help readers quickly locate specific information. -Implementing these conventions can contribute to creating a textbook that is comprehensive, accessible, and conducive to effective learning. +Implementing these conventions can contribute to creating a textbook that is +comprehensive, accessible, and conducive to effective learning.