feat: add more special characters to allowlist (#389)

sebastiaanspeck · web-flow · commit cd19a8d54600 · 2025-06-10T06:02:39.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com).
 
 ## [v0.0.19](https://github.com/tldr-pages/tldr-lint/compare/v0.0.18...v0.0.19)
 
+### Added
+
+- Add `{`, `%`, `,`, `^`, `~`, `$`, `~`, and `.` as allowed characters in file names and page titles ([#389](https://github.com/tldr-pages/tldr-lint/pull/389))
+
 ### Changed
 
 - Switched to Node.js 22 ([#393](https://github.com/tldr-pages/tldr-lint/pull/393))
@@ -15,13 +19,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com).
 
 ### Added
 
-- Add `!` as allowed characters in page titles ([#386](https://github.com/tldr-pages/tldr-lint/pull/386))
+- Add `!` as allowed characters in file names and page titles ([#386](https://github.com/tldr-pages/tldr-lint/pull/386))
 
 ## [v0.0.17 - 2025-03-31](https://github.com/tldr-pages/tldr-lint/compare/v0.0.16...v0.0.17)
 
 ### Added
 
-- Add `]` and `}` as allowed characters in page titles ([#378](https://github.com/tldr-pages/tldr-lint/pull/378))
+- Add `]` and `}` as allowed characters in file names and page titles ([#378](https://github.com/tldr-pages/tldr-lint/pull/378))
 
 ## [v0.0.16 - 2024-10-04](https://github.com/tldr-pages/tldr-lint/compare/v0.0.15...v0.0.16)
 
diff --git a/lib/tldr-parser.js b/lib/tldr-parser.js
diff --git a/specs/pages/passing/$.md b/specs/pages/passing/$.md
@@ -0,0 +1,32 @@
+# $
+
+> Expand a Bash variable.
+> More information: <https://gnu.org/software/bash/manual/bash.html#Shell-Variables>.
+
+- Print a variable:
+
+`echo ${{VARIABLE}}`
+
+- Print the exit status of the previous command:
+
+`echo $?`
+
+- Print a random number between 0 and 32767:
+
+`echo $RANDOM`
+
+- Print one of the prompt strings:
+
+`echo ${{PS0|PS1|PS2|PS3|PS4}}`
+
+- Expand with the output of `command` and run it. Same as enclosing `command` in backtics:
+
+`$({{command}})`
+
+- List how many arguments the current context has:
+
+`echo $#`
+
+- Print out a Bash array:
+
+`echo ${array[@]}`
diff --git a/specs/pages/passing/%.md b/specs/pages/passing/%.md
@@ -0,0 +1,28 @@
+# %
+
+> Manage jobs.
+> More information: <https://www.gnu.org/software/bash/manual/bash.html#Job-Control-Basics>.
+
+- Bring the current job to front:
+
+`%`
+
+- Bring the previous job to front:
+
+`%-`
+
+- Bring the job number `n` to front:
+
+`%{{n}}`
+
+- Bring a job whose command starts with `string` to front:
+
+`%{{string}}`
+
+- Bring a job whose command contains `string` to front:
+
+`%?{{string}}`
+
+- Resume a suspended job:
+
+`%{{1}} &`
diff --git a/specs/pages/passing/+.md b/specs/pages/passing/+.md
diff --git a/specs/pages/passing/,.md b/specs/pages/passing/,.md
@@ -0,0 +1,16 @@
+# ,
+
+> Run commands without installing them.
+> More information: <https://github.com/nix-community/comma>.
+
+- Run a command:
+
+`, {{command -with -flags}}`
+
+- Add a command to a child shell:
+
+`, {{[-s|--shell]}} {{command}}`
+
+- Clear the cache:
+
+`, {{[-e|--empty-cache]}}`
diff --git a/specs/pages/passing/..md b/specs/pages/passing/..md
@@ -0,0 +1,7 @@
+# .
+
+> This command is an alias of `source`.
+
+- View documentation for the original command:
+
+`tldr source`
diff --git a/specs/pages/passing/[.md b/specs/pages/passing/[.md
@@ -0,0 +1,33 @@
+# [
+
+> Check file types and compare values.
+> Returns a status of 0 if the condition evaluates to true, 1 if it evaluates to false.
+> More information: <https://gnu.org/software/bash/manual/bash.html#index-test>.
+
+- Test if a given variable is equal/not equal to the specified string:
+
+`[ "${{variable}}" {{=|!=}} "{{string}}" ]`
+
+- Test if a given variable is [eq]ual/[n]ot [e]qual/[g]reater [t]han/[l]ess [t]han/[g]reater than or [e]qual/[l]ess than or [e]qual to the specified number:
+
+`[ "${{variable}}" -{{eq|ne|gt|lt|ge|le}} {{integer}} ]`
+
+- Test if the specified variable has a [n]on-empty value:
+
+`[ -n "${{variable}}" ]`
+
+- Test if the specified variable has an empty value ([z]ero length):
+
+`[ -z "${{variable}}" ]`
+
+- Test if the specified [f]ile exists:
+
+`[ -f {{path/to/file}} ]`
+
+- Test if the specified [d]irectory exists:
+
+`[ -d {{path/to/directory}} ]`
+
+- Test if the specified file or directory [e]xists:
+
+`[ -e {{path/to/file_or_directory}} ]`
diff --git a/specs/pages/passing/[[.md b/specs/pages/passing/[[.md
@@ -0,0 +1,37 @@
+# [[
+
+> Check file types and compare values.
+> Returns a status of 0 if the condition evaluates to true, 1 if it evaluates to false.
+> More information: <https://gnu.org/software/bash/manual/bash.html#index-_005b_005b>.
+
+- Test if a given variable is equal/not equal to the specified string:
+
+`[[ ${{variable}} {{==|!=}} "{{string}}" ]]`
+
+- Test if a given string conforms the specified glob/regex:
+
+`[[ ${{variable}} {{==|=~}} {{pattern}} ]]`
+
+- Test if a given variable is [eq]ual/[n]ot [e]qual/[g]reater [t]han/[l]ess [t]han/[g]reater than or [e]qual/[l]ess than or [e]qual to the specified number:
+
+`[[ ${{variable}} -{{eq|ne|gt|lt|ge|le}} {{integer}} ]]`
+
+- Test if the specified variable has a [n]on-empty value:
+
+`[[ -n ${{variable}} ]]`
+
+- Test if the specified variable has an empty value ([z]ero length):
+
+`[[ -z ${{variable}} ]]`
+
+- Test if the specified [f]ile exists:
+
+`[[ -f {{path/to/file}} ]]`
+
+- Test if the specified [d]irectory exists:
+
+`[[ -d {{path/to/directory}} ]]`
+
+- Test if the specified file or directory [e]xists:
+
+`[[ -e {{path/to/file_or_directory}} ]]`
diff --git a/specs/pages/passing/].md b/specs/pages/passing/].md
@@ -0,0 +1,7 @@
+# ]
+
+> This shell keyword is used to close out `[`.
+
+- View documentation for the `[` keyword:
+
+`tldr [`
diff --git a/specs/pages/passing/]].md b/specs/pages/passing/]].md
@@ -0,0 +1,7 @@
+# ]]
+
+> This shell keyword is used to close out `[[`.
+
+- View documentation for the `[[` keyword:
+
+`tldr [[`
diff --git a/specs/pages/passing/^.md b/specs/pages/passing/^.md
@@ -0,0 +1,21 @@
+# ^
+
+> Bash builtin to quick substitute a string in the previous command and run the result.
+> Equivalent to `!!:s^string1^string2`.
+> More information: <https://gnu.org/software/bash/manual/bash.html#Event-Designators>.
+
+- Run the previous command replacing `string1` with `string2`:
+
+`^{{string1}}^{{string2}}`
+
+- Remove `string1` from the previous command:
+
+`^{{string1}}^`
+
+- Replace `string1` with `string2` in the previous command and add `string3` to its end:
+
+`^{{string1}}^{{string2}}^{{string3}}`
+
+- Replace all occurrences of `string1`:
+
+`^{{string1}}^{{string2}}^:&`
diff --git a/specs/pages/passing/{.md b/specs/pages/passing/{.md
@@ -0,0 +1,36 @@
+# {
+
+> Multipurpose shell syntax.
+> More information: <https://www.gnu.org/software/bash/manual/bash.html>.
+
+- Isolate variable names:
+
+`echo ${HOME}work`
+
+- Brace expand sequences:
+
+`echo {1..3} {a..c}{dir1,dir2,dir3}`
+
+- Check if `variable` is set before returning text:
+
+`echo ${variable:+variable is set and contains $variable}`
+
+- Set default values in case `variable` is unset:
+
+`echo ${variable:-default}`
+
+- Return `variable` length in characters:
+
+`echo ${#variable}`
+
+- Return a string slice:
+
+`echo ${variable:3:7}`
+
+- Recursively expand a `variable`:
+
+`echo ${!variable}`
+
+- Group command output together:
+
+`{ {{command1; command2; ...}} } | {{another_command}}`
diff --git a/specs/pages/passing/}.md b/specs/pages/passing/}.md
@@ -0,0 +1,7 @@
+# }
+
+> This shell keyword is used to close out `{`.
+
+- View documentation for the `{` keyword:
+
+`tldr {`
diff --git a/specs/pages/passing/~.md b/specs/pages/passing/~.md
@@ -0,0 +1,16 @@
+# ~
+
+> Expand to a directory.
+> More information: <https://gnu.org/software/bash/manual/bash.html#Tilde-Expansion>.
+
+- List the current user's home directory contents:
+
+`ls ~`
+
+- List the home directory contents of another user:
+
+`ls ~{{username}}`
+
+- List the contents of the previous directory you were in:
+
+`ls ~-`
diff --git a/specs/tldr-lint.spec.js b/specs/tldr-lint.spec.js
@@ -187,12 +187,12 @@ describe('Common TLDR formatting errors', function() {
 
   const invalidCharacters = ['<', '>', ':', '"', '/', '\\', '|', '?', '*'];
   invalidCharacters.forEach((char) => {
-    it('TLDR111\t' + linter.ERRORS.TLDR111 + '\t - ${char}', function() {
+    it('TLDR111\t' + linter.ERRORS.TLDR111 + `: '${char}'`, function() {
       const basenameSpy = jest.spyOn(path, 'basename').mockImplementation((filePath) => {
         return `111${char}`;
       });
 
-      let errors = lintFile(`pages/failing/111.md`).errors;
+      let errors = lintFile('pages/failing/111.md').errors;
       expect(containsOnlyErrors(errors, 'TLDR111')).toBeTruthy();
       expect(errors.length).toBe(1);
 
@@ -217,16 +217,14 @@ describe('TLDR pages that are simply correct', function() {
     expect(errors.length).toBe(0);
   });
 
-  it('Page filename and title includes + symbol', function() {
-    let errors = lintFile('pages/passing/title++.md').errors;
-    expect(errors.length).toBe(0);
+  const validCharacters = [',', '!', '.', '[', '[[', ']', ']]', '{', '}', '%', '^', '+', '~', '$']
+  validCharacters.forEach((char) => {
+    it(`Page filename and title includes '${char}' symbol`, function() {
+      let errors = lintFile(`pages/passing/${char}.md`).errors;
+      expect(errors.length).toBe(0);  
+    });
   });
 
-  it('Page filename and title includes ! symbol', function() {
-    let errors = lintFile('pages/passing/!.md').errors;
-    expect(errors.length).toBe(0);
-  })
-
   it('Certain words are always written in lower case', function() {
     let errors = lintFile('pages/passing/lower-case.md').errors;
     expect(errors.length).toBe(0);
diff --git a/tldr.l b/tldr.l
@@ -99,7 +99,12 @@ space [ \t]
 %{
   if (this.topState() === "title") {
     yytext = this.matches[1];
-    if (this.matches[1].match(/([^\w+\[\]}!. -])|(\.$)/)) yy.error(yylloc, 'TLDR013');
+    if (
+      /[^\w+\[\]{}!%,^~$. \-]/.test(yytext) || 
+      (yytext.endsWith('.') && yytext !== '.' && yytext !== ' .')
+    ) {
+      yy.error(yylloc, 'TLDR013');
+    }
     this.checkTrailingWhitespace(this.matches[2], yylloc);
     this.checkNewline(this.matches[3], yylloc);
     this.popState();
