16 Commits

Author SHA1 Message Date
Gabriele Ciccotelli
caa05be694 Add RTL/LTR Markdown linter for mixed-direction text consistency and PR annotation (#11877)
* Add RTL/LTR Markdown linter for mixed-direction text consistency and PR annotation

Introduce a Python-based linter (scripts/rtl_ltr_linter.py) to automatically detect and annotate issues related to mixed Right-To-Left (RTL) and Left-To-Right (LTR) text in Markdown files. The linter analyzes list items, book entries, and metadata for potential bidirectional text rendering problems, such as missing Unicode directionality markers (RLM/LRM) and improper handling of LTR keywords or symbols in RTL contexts.

Key features:
- Scans all Markdown files in the repository, with full logs saved as workflow artifacts.
- Annotates only changed or added lines in pull requests, providing targeted feedback in the GitHub Actions Job Summary.
- Detects common RTL/LTR issues, including:
  - Missing directionality markers after LTR keywords (e.g., "HTML") or symbols (e.g., "C#") in RTL text.
  - BIDI (bidirectional) mismatches that may affect text display.
  - Incorrect ordering of author names and metadata in RTL contexts.
- Configurable via rtl_linter_config.yml for keywords, symbols, and severity levels.
- Includes a GitHub Actions workflow (rtl-ltr-linter.yml) for automated checks on PRs.

* Add test cases for RTL/LTR linter in English and Arabic book lists

Add sample entries to free-programming-books-en.md and free-programming-books-ar.md to test the RTL/LTR Markdown linter.
These test cases include various combinations of RTL and LTR text, keywords, symbols, and metadata to verify that the linter correctly detects directionality issues and outputs the expected logs and annotations.

* Restore original book lists after RTL/LTR linter test cases

Revert test entries in free-programming-books-en.md and free-programming-books-ar.md, restoring the original book lists. This commit removes temporary test data used for validating the RTL/LTR Markdown linter, preparing the repository for merging the PR with a clean state.

No functional changes to the linter or configuration files; only test content has been removed.

* Update RTL/LTR linter workflow and script: run only on RTL file changes or "RTL" label, fail only on errors

The GitHub Actions workflow for the RTL/LTR Markdown linter now runs only if:
- The PR modifies .md files related to RTL languages (ar, he, fa, ur), or
- The PR has the "RTL" label.
The linter script has been updated to fail the check only if errors are found on changed lines, not for warnings.

* Only upload linter artifact if linter step runs

Prevent warning about missing artifact by uploading the linter output log only if the linter step was executed (success or failure). This avoids unnecessary warnings when the linter is skipped because no RTL files were changed and no RTL label is present.

* Test workflow: modify non-RTL markdown file

Modified free-programming-books-en.md to verify that the RTL/LTR linter workflow does not run when only non-RTL markdown files are changed and the "RTL" label is not present.

* Test workflow: modify RTL markdown file to trigger linter

Modified free-programming-books-ar.md to verify that the RTL/LTR linter workflow runs as expected when an RTL markdown file is changed.

* Fix RTL/LTR BIDI issues in some markdown files

Applied directional markers (‎, ‏) and other formatting fixes to resolve BIDI (bidirectional text) errors and warnings reported by the linter in several .md files.

* Fix workflow: upload linter log only if linter step has not been skipped

Updated the workflow to upload the linter output artifact only when the linter step was actually executed (not skipped)

* Add debug step to check linter outcome in workflow

Added a debug step after the linter execution in the workflow to print the outcome and conclusion of the run_linter step.

* Set continue-on-error for linter step to allow artifact upload and debug

* Remove workflow debug step and update markdown file

Removed the debug step from the RTL/LTR linter workflow and applied further changes to a markdown file.

* Fix RTL/LTR BIDI issues in some markdown files

Applied directional markers (‎, ‏) and other formatting fixes to resolve BIDI (bidirectional text) errors and warnings reported by the linter in several .md files. This commit is a second batch of corrections to improve RTL/LTR rendering and pass the linter checks.

* Fix RTL/LTR BIDI issues in some markdown files

Applied directional markers (‎, ‏) and other formatting fixes to resolve BIDI (bidirectional text) errors and warnings reported by the linter in several .md files. This commit is a third batch of corrections to improve RTL/LTR rendering and pass the linter checks.

* Do not produce log file if no issues found

Updated the linter script to avoid creating the log file when no issues, warnings, or notices are found. If no issues are detected, the script now prints a "::notice ::No issues found"

* Always print annotation with number of errors and warnings found

Updated the linter script to always print an annotation indicating how many errors and warnings were found, even if there are none.

* Fix: always print summary annotation with number of issues found

* Add a missing newline character at end of file free-courses-he.md

* Update linter configuration and revert markdown files to pre-fix state

Updated the organization of keywords and symbols in the linter configuration file. Reverted all markdown files to their original state prior to the fixes.

* Update free-programming-books-he.md with fixes

* Update free-programming-books-he.md with further fixes

* Update free-programming-books-he.md with fixes

* Update free-programming-books-fa_IR.md with fixes

* Update free-programming-books-he.md with further fixes

* Update free-programming-books-ar.md with fixes

* Update free-programming-books-ar.md with further fixes

* Update free-podcasts-screencasts-ar.md with fixes

* Update free-podcasts-screencasts-fa_IR.md with fixes

* Update free-courses-he.md with fixes

* Update free-courses-he.md with further fixes

* Update free-courses-fa_IR.md with fixes

* Update free-courses-fa_IR.md with further fixes

* Update free-courses-ar.md with fixes

* Update free-courses-ar.md with further fixes

* Update free-courses-ar.md with further fixes

* Update free-courses-ur.md with fixes

* Update some markdown files with further improvements

* Fix alignment of nested lists in free-programming-books-fa_IR.md

* Update CONTRIBUTING.md and CONTRIBUTING-it.md with RTL/LTR linter error fixing guidelines

Added a section to CONTRIBUTING.md and CONTRIBUTING-it.md explaining how to fix RTL/LTR Markdown linter errors, including when to use ‏ and ‎ with practical examples for contributors working on files with mixed RTL and LTR text
2025-05-28 10:46:25 -04:00
Eric Hellman
10d7289c1e testing the license label (#11269)
* testing the license label

tests #11260

* maybe a comma will work

* another try

* documentation for license notes

* Update CONTRIBUTING.md

* tweaks
2024-10-07 12:15:34 -04:00
David Ordás
59e4fba4b6 format: syntax of in-process anotation should be *(🚧 in process)* (#7036)
* format: update syntax of `in process` anotation (CONTRIBUTING-*)

from (🚧 *in process*)
to   *(🚧 in process)*

* format: apply notes syntax to `in_process` resources

- Applied note `*(🚧 in process)*` translating `in process` to underlying language there where we have previous translated text
- Used regex to detect most of notes: `((\*[^\*]+\*)|(_[^_]+_))`

* apply to new resources added in #7082

* Update books/free-programming-books-subjects.md

Co-authored-by: Leithen <lcrider@cvent.com>

---------

Co-authored-by: Eric Hellman <eric@hellman.net>
Co-authored-by: Leithen <lcrider@cvent.com>
2023-11-29 17:15:41 -05:00
Soniya Prasad
3c6448ce4b Update CONTRIBUTING.md (#9897)
* Update CONTRIBUTING.md

* Update CONTRIBUTING.md
2023-10-06 12:21:11 -04:00
Varshaa Shetty
573d1576ae Updated CONTRIBUTING.md (#9614) 2023-10-01 21:06:44 -04:00
Eric Hellman
933bb43f73 add guidance for things that have confused submitters (#8152)
* add guidance that has been and issue

* add notes on time limits
2022-10-12 22:11:42 -04:00
David Ordás
e091eeedf0 docs(CONTRIBUTING): complete creators guidelines with relator terms (#7102)
* complete creators guidelines with relator terms

* Update CONTRIBUTING.md

minor language editing

* Update CONTRIBUTING.md

recover missing MARC relators URL to complete empty link

* chore: copy ENG missing texts to translated files

* chore: translate new texts to spanish

* chore: translate new text to italian

Co-authored-by: ImVector <59611597+LuigiImVector@users.noreply.github.com>

Co-authored-by: Eric Hellman <eric@hellman.net>
Co-authored-by: ImVector <59611597+LuigiImVector@users.noreply.github.com>
2022-09-29 10:59:39 -04:00
ImVector
0aa949975c docs(CONTRIBUTING): improve guidelines (#6878)
* docs(CONTRIBUTING): improve guidelines

* docs(CONTRIBUTING): new section

* Update docs/CONTRIBUTING.md

Co-authored-by: CleanMachine1 <78213164+CleanMachine1@users.noreply.github.com>

* docs(CONTRIBUTING)

Co-authored-by: CleanMachine1 <78213164+CleanMachine1@users.noreply.github.com>

* Update docs/CONTRIBUTING.md

Co-authored-by: CleanMachine1 <78213164+CleanMachine1@users.noreply.github.com>
2022-06-21 14:15:21 -04:00
David Ordás
6a4db2b978 docs(contributing): Add playground definition (#6822)
* Added playground definition

Added a small definition about programming/coding playgrounds for making it understandable to beginners

* Define what is a playground

Via / completes:
- What's a programming playground? #6107
- Added playground definition #6817
- Sentence added under playground #6819

Thanks @Suman373 for the initial idea.

Co-authored-by: Suman Roy <95040233+Suman373@users.noreply.github.com>

* reword playground definition as suggested

Co-authored-by: Eric Hellman <eric@hellman.net>

Co-authored-by: Suman Roy <95040233+Suman373@users.noreply.github.com>
Co-authored-by: Eric Hellman <eric@hellman.net>
2022-04-12 12:27:59 -04:00
David Ordás
0e9ad7e994 chore: HTML5 anchors compilant <a name= > <a id= (#6730)
* HTML5 anchors compilant `<a name=>` > `<a id=` for books

* HTML5 anchors compilant `<a name=>` > `<a id=` for courses

* HTML5 anchors compilant `<a name=>` > `<a id=` for contribs

* HTML5 anchors compilant `<a name=>` > `<a id=` for casts

* HTML5 anchors compilant `<a name=>` > `<a id=` for cheats

* HTML5 anchors compilant `<a name=>` > `<a id=` for interactives

* HTML5 anchors compilant `<a name=>` > `<a id=` for playgrounds
2022-02-25 11:23:35 -05:00
ImVector
92f1e7bc10 fix(docs): Bad target url #6721 (#6722)
* fix(docs): Bad target url #6721

* fix(docs): Bad target url #6721
2022-02-13 15:58:11 -05:00
David Ordás
7a8349abfe feat: Add docs/readme.md + update crosslinks (#6700)
* complete translate list with the new languages appeared since hacktoberfest

* Create docs/README.md with the translations section

using root README.md as source. Links are adapted to this folder

Address EbookFoundation/free-programming-books#6698

* fix remaining url + translation items

- Portuguese (Portugal)
- Slovak / slovenčina
- Slovenian / slovenščina

Address EbookFoundation/free-programming-books#6698

* fix remaining url + translation items

- Portuguese (Portugal)
- Slovak / slovenčina
- Slovenian / slovenščina

Address EbookFoundation/free-programming-books#6698

* Add inclusiveness `dare to translate...` paragraph

* Add inclusiveness `dare to translate...` paragraph

* Move translations link target url to docs

* move translation links `bs`

* move translations link `en`

* move translations crosslink `es`

* move translations crosslink `fr`

* move translations crosslink `de`

* move translations crosslink `el`

* move translations crosslink `fa_IR`

* move translations crosslink `fil`

* move translations crosslink `it`

* move translations crosslink `pt_BR`

* move translations crosslink `ko`

* move translations crosslink `ru`

* move translations crosslink `id`

* move translations crosslink `zh`

* move translations crosslink `hi`

* move translations crosslink `pl`

* move translations crosslink `uk`

* move translations crosslink `vi`

* move translations crosslink remaining `HOW-To's`

* revert feature moved to #6688

* Remove the list from the top level. Leave `en` links

* use `previous languages` in root README

* Add more languages lists in root `readme.md`

* fix typo

* fix typo

* Update docs/README.md after translations paragraph

Less text is more

Co-authored-by: Eric Hellman <eric@hellman.net>

* Update README.md after translations paragraph 

Less text is more

Co-authored-by: Eric Hellman <eric@hellman.net>

* Update README.md preface translations paragraph 

Co-authored-by: Eric Hellman <eric@hellman.net>

* fix CONTRIBUTING target url commited at fd2b39151c

* Update docs/README.md preface translations paragraph 

Co-authored-by: Eric Hellman <eric@hellman.net>

* read me! said the boss ^^,

less text is more.

Co-authored-by: Eric Hellman <eric@hellman.net>

* remove "The inclusiveness is one of our targets, so "

Co-authored-by: Eric Hellman <eric@hellman.net>
2022-02-11 12:27:07 -05:00
David Ordás
84438cb1df docs(contributing): Homogenize format across translated files (#6625)
* docs(contributing): remove trailing spaces

* docs(contributing): Apply headings `2-1` empty lines lint rule

* docs(contributing): Apply headings `2-1` empty lines lint rule

forgotten in previous commit: e83220aa4c

* docs(contributing): Move anchor alias to inside list items

... there where an anchor alias `<a name="...">` is used near to each of those list items

This solves markdownlint `MD032/blanks-around-lists` issue

* docs(contributing): Homogenize `1` blank line in nutshell enumeration

* docs(contributing): Homogenize `1` blank line inside Formatting section

* docs(contributing): Ensure `4-spaces` indent `.editorconfig` param

* docs(contributing): Homogenize format & indent of code blocks

- Format using fenced style.
- Well indent in those placed inside list enumerations.
- Simulate `Good` - `Bad` monospace double colon indent inside each one.

- Examples highlighting as `text-plain`. The `md, markdown` style doesn't work very well since blocks has mixed syntax.
- `check_urls` code block highlighted as `properties` style (key-value pair).

Solves markdownlint rules:
- MD040/fenced-code-language: Fenced code blocks should have a language specified
- MD046/code-block-style: Code block style [Expected: indented; Actual: fenced]

* docs(contributing): Ensure `4-spaces` indent `.editorconfig` param

Forgotten in commit: 31c776cb52

* docs(contributing): Homogenize format & indent of code blocks

- Simulate `Good` - `Bad` monospace double colon indent inside each one.

Revert commit f9dc719aef only in this file after check non-needs in a deployed web snapshot

* docs(contributing): Use "consistent" unordered list mark

Solves markdownlint rules:
MD004/ul-style: Unordered list style "consistent"

* docs(contributing): Solve `no-space-in-*` lint rules

markdownlint rules:
MD037/no-space-in-emphasis: Spaces inside emphasis
MD038/no-space-in-code: Spaces inside code span elements
MD039/no-space-in-links: Spaces inside link text

* docs(contributing): Move some punctuation just before any closing brackets after it

* docs(contributing): Hack highlight IDE/Editors headings+HTML

It apply the hack to highlight in IDE/Editors those headings with an anchor alias just before itself

* docs(contributing): Homogenize Pull Request acronym

* docs(contributing): Fix `GitHub` trademark typos

* docs(contributing): ALLCAPS

* docs(contributing): Git trademark

* docs(contributing): YouTube trademark

* docs(contributing): ISBN acronym

* fix: flag emoji code `en` > `us`

Resolves d775cb34fb (commitcomment-59537594)

#5831: `:en:` emoji flag markup doesn't work. Use `🇺🇸` 🇺🇸 or `🇬🇧` 🇬🇧

d775cb34fb (diff-b35eb40c148657d4ea1361c44496e11c5625f484a4c6040c022770e88cbcfdccR8-R10)

* docs(contributing): Fix fa_IR broken anchors

* docs(contributing): filenames in monospace font

* docs(contributing): Homogenize `check_urls=file_to_check`

* docs(contributing): literals/markup texts in monospace font

- `et al.`
- File extensions `.md`
- Protocols: `http`, `https`...
- Notes: LeanPub, require email, StackOverflow, in process, archived

trailing dots in that lines

* docs(contributing): linkify wayback machine

* docs(contributing): Fix `Leanpub` trademark typos

* chore: Rename `master` to `main` #blacklivesmatter

Resolves EbookFoundation/free-programming-books#5803

* docs(contributing): fix broken ref link to `programming-playgrounds`

Fix over EbookFoundation/free-programming-books#5449 and commit 3c42c3629e

(cherry picked from commit 59ebfe3f97e318fa43d58877cbc5bfdd8b0c7426)

* docs(contributing): fix repo urls on initial FR translation

- `ElivreFoundation` -> `EbookFoundation`
- `free-programming-livres` ->`free-programming-books`

PR: #5554
Commit: e629db6b05

Affected lines: 
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45)

* docs(contributing): use relative urls EN

Via #6614

* docs(contributing): greek. place translations link in right place

Via #6614

* Merge EbookFoundation/free-programming-books#6631 upstream/main commit into docs/contributing/sync/1

* Add repo badges (see EbookFoundation/free-programming-books#5983)

(cherry picked from a16a79b12d solving merge conflict)

* Merge EbookFoundation/free-programming-books#6662 upstream/main commit into docs/contributing/sync/1

* Apply centering proposed at #5983 but not implemented in #6631

(cherry picked from commit f36fd03c06)

* format(contributing): Bold 5th nutshell equal zh

* Merge #6677 upstream/main commit into docs/contributing/sync/1

fix(docs): Use Kramdown processor (#6677)
* Update _config.yml
* add markdown="1"
* update url
* complete removing spaces?
* explicitly use kramdown

(cherry picked from commit de2f31976f)
2022-02-02 20:39:27 -05:00
ImVector
a16a79b12d Add badges (#6631)
* Added badges

* Fixed bug #6631

* Removed CoC badge
2021-12-06 10:52:29 -05:00
David Ordás
ee4b9ee1f9 chore: Rename master to main #blacklivesmatter (#6627)
* chore: Rename `master` to `main` #blacklivesmatter

Resolves EbookFoundation/free-programming-books#5803

* docs(contributing): fix broken ref link to `programming-playgrounds`

Fix over EbookFoundation/free-programming-books#5449 and commit 3c42c3629e

(cherry picked from commit 59ebfe3f97e318fa43d58877cbc5bfdd8b0c7426)

* fix: Complete #6614 upstream/main merge

Over commit: 4d3c9fe11c

Co-authored-by: ImVector <59611597+LuigiImVector@users.noreply.github.com>

Co-authored-by: ImVector <59611597+LuigiImVector@users.noreply.github.com>
2021-11-23 09:25:57 -05:00
Eric Hellman
868d94730a move the translated documentation files to a docs folder (#6614)
* new branch for misc cleanup

* add item to resolve #6319

* fix grammar

* re-collate

* centralize all the translation links

* one more

* fix link

* localize labels

* move files

* fix links

* indent in arabic

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* typos

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* remove

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* translation

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* translation

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* mixed markdown

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* period

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* missing *

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* Update docs/HOWTO-pl.md

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* Update docs/HOWTO-th.md

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* translated

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* translate

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* lower case

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* typo

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* wording

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* translations link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* space

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* space

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* typo

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* Update CONTRIBUTING-de.md

* space

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* parens not brackets

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* add #6619

* chore: resolve dead code CONTRIB-es

Addressed at https://github.com/EbookFoundation/free-programming-books/pull/6614#commitcomment-60517997

Review suggestion: https://github.com/EbookFoundation/free-programming-books/pull/6614#discussion_r751697277

* chore: use spanish translated text for "translations"

Review suggestion: https://github.com/EbookFoundation/free-programming-books/pull/6614#discussion_r751697277

* chore: DRY. Use markdown link refs as translations target

Review suggestion: https://github.com/EbookFoundation/free-programming-books/pull/6614#discussion_r751697277

* fix: revert removed parens in previous commit 6276a21d85

Review suggestion: https://github.com/EbookFoundation/free-programming-books/pull/6614#discussion_r751697277

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* lint

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* lint

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* lint

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* lint

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* fix link

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* space

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

* translate

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>

Co-authored-by: David Ordás <3125580+davorpa@users.noreply.github.com>
2021-11-20 13:25:15 -05:00