Format Markdown files with elvmdfmt.

.github/workflows/ci.yml

@@ -121,16 +121,10 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v2
-    - name: Set up environment
-      run: |
-        echo "NPM_PREFIX=$HOME/npm" >> $GITHUB_ENV
-        echo "PATH=$HOME/npm/bin:$PATH" >> $GITHUB_ENV
-    - name: Set up Node
-      uses: actions/setup-node@v2
-    - name: Set up Node prefix
-      run: npm config set prefix $NPM_PREFIX
-    - name: Set up prettier
-      run: npm install --global prettier@2.7.1
+    - name: Set up Go
+      uses: actions/setup-go@v2
+      with:
+        go-version: 1.19.x
     - name: Check style
       run: ./tools/checkstyle-md.sh
 

.prettierrc

@@ -1,4 +0,0 @@
-{
-    "tabWidth": 4,
-    "proseWrap": "always"
-}

CONTRIBUTING.md

@@ -57,7 +57,7 @@ appropriate section. You can find the document at the root of the repo (called
 ### Reference docs
 
 Reference docs are interspersed in Go sources as comments blocks whose first
-line starts with `//elvdoc` (and are hence called _elvdocs_). They can use
+line starts with `//elvdoc` (and are hence called *elvdocs*). They can use
 [Github Flavored Markdown](https://github.github.com/gfm/).
 
 Elvdocs for functions look like the following:
@@ -150,20 +150,30 @@ Some basic aspects of code hygiene are checked in the CI.
 ### Formatting
 
 Install [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) to
-format Go files, and [prettier](https://prettier.io/) to format Markdown files.
+format Go files.
 
 ```sh
 go install golang.org/x/tools/cmd/goimports@latest
-npm install --global prettier@2.7.1
 ```
 
-Once you have installed the tools, use `make style` to format Go and Markdown
-files. If you prefer, you can also configure your editor to run these commands
-automatically when saving Go or Markdown sources.
+The Markdown formatter [elvmdfmt](cmd/elvmdfmt) does not need to be installed.
 
-Use `make checkstyle` to check if all Go and Markdown files are properly
+Once you have installed the tools, use `make style` to format Go and Markdown
+files, or `make checkstyle` to check if all Go and Markdown files are properly
 formatted.
 
+#### Installing elvmdfmt
+
+The `make style` and `make checkstyle` scripts both use `elvmdfmt` is by running
+`go run src.elv.sh/cmd/elvmdfmt`. Besides not needing to install the tool, this
+also has the advantage of always using the `elvmdfmt` from the repo itself.
+
+You can use the same `go run` command to run `elvmdfmt`, but it has a small
+performance penalty. If you need to run it frequently (for example on every
+editor save), you can also install it with `go install`. Beware that this means
+you have to re-install it every time there is a change in the output format of
+`elvmdfmt` (which should be infrequent but possible).
+
 ### Linting
 
 Install [staticcheck](https://staticcheck.io):

Makefile

@@ -31,7 +31,7 @@ cover:
 style:
 	find . -name '*.go' | xargs goimports -w
 	find . -name '*.go' | xargs gofmt -s -w
-	find . -name '*.md' | xargs prettier --write
+	find . -name '*.md' | xargs go run src.elv.sh/cmd/elvmdfmt -w -width 80
 
 # Check if the style of the Go and Markdown files is correct without modifying
 # those files.

README.md

@@ -98,7 +98,7 @@ directory already in `$PATH`.
 
 ### Building a variant
 
-Elvish has several _build variants_ with slightly different feature sets. For
+Elvish has several *build variants* with slightly different feature sets. For
 example, the `withpprof` build variant has
 [profiling support](https://pkg.go.dev/runtime/pprof).
 

tools/checkstyle-md.sh

@@ -3,26 +3,8 @@
 # Check if the style of the Markdown files is correct without modifying those
 # files.
 
-# The `prettier` utility doesn't provide a "diff" option. Therefore, we have
-# to do this in a convoluted fashion to get a diff from the current state to
-# what `prettier` considers correct and reporting, via the exit status, that
-# the check failed.
-
-# We predicate the detailed diff on being in a CI environment since we don't
-# care if the files are modified. If not, just list the pathnames that need to
-# be reformatted without actually modifying those files.
-
-if test "$CI" = ""; then
-    echo 'Markdown files that need changes:'
-    ! find . -name '*.md' |
-        xargs prettier --list-different |
-        sed 's/^/  /' | grep . && echo '  None!'
-else
-    echo 'Markdown files need these changes:'
-    if ! find . -name '*.md' | xargs prettier --check >/dev/null; then
-        find . -name '*.md' | xargs prettier --write >/dev/null
-        find . -name '*.md' | xargs git diff
-        exit 1
-    fi
-    echo '  None!'
+echo 'Markdown files that need changes:'
+if find . -name '*.md' | grep -v '/node_modules/' | xargs go run src.elv.sh/cmd/elvmdfmt -width 80 -d | grep .; then
+    exit 1
 fi
+echo '  None!'

website/blog/0.11-release-notes.md

@@ -95,8 +95,8 @@ As usual, prebuilt binaries can be found in [get](../get/).
 ## Editor
 
 -   A maximum wait time can be specified with
-    [\$edit:-prompts-max-wait](../ref/edit.html#edit-prompts-max-wait) to
-    prevent slow prompt functions from blocking UI updates
+    [$edit:-prompts-max-wait](../ref/edit.html#edit-prompts-max-wait) to prevent
+    slow prompt functions from blocking UI updates
     ([#482](https://github.com/elves/elvish/issues/482)).
 
 -   Execution of hook functions are now correctly isolated

website/blog/newsletter-july-2017.md

@@ -100,8 +100,8 @@ For general questions, you are welcome in
 # Conclusion
 
 This concludes this first issue of the newsletter. Hopefully future issues of
-this newsletter will also feature blog posts from Elvish users like _Elvish for
-Python Users_ and popular Elvish modules like _Tetris in Your Shell_ :)
+this newsletter will also feature blog posts from Elvish users like *Elvish for
+Python Users* and popular Elvish modules like *Tetris in Your Shell* :)
 
 Have Fun with Elvish!
 

website/blog/newsletter-sep-2017.md

@@ -64,8 +64,8 @@ very tuned.
 
 # Conclusions
 
-In the last newsletter, I predicted that we will be featuring _Elvish for Python
-Users_ and _Tetris in Your Shell_ in a future newsletter. It seems we are
+In the last newsletter, I predicted that we will be featuring *Elvish for Python
+Users* and *Tetris in Your Shell* in a future newsletter. It seems we are
 getting close to that pretty steadily.
 
 Have fun with Elvish!

website/learn/effective-elvish.md

@@ -9,8 +9,8 @@ This document is an advanced tutorial focusing on how to write idiomatic Elvish
 code, code that is concise and clear, and takes full advantage of Elvish's
 features.
 
-An appropriate adjective for idiomatic Elvish code, like _Pythonic_ for Python
-or _Rubyesque_ for Ruby, is **Elven**. In
+An appropriate adjective for idiomatic Elvish code, like *Pythonic* for Python
+or *Rubyesque* for Ruby, is **Elven**. In
 [Roguelike games](https://en.wikipedia.org/wiki/Roguelike), Elven items are
 known to be high-quality, artful and resilient. So is Elven code.
 
@@ -89,7 +89,7 @@ section documents how to make the most use of pipelines.
 ## Returning Values with Structured Output
 
 Unlike functions in most other programming languages, Elvish commands do not
-have return values. Instead, they can write to _structured output_, which is
+have return values. Instead, they can write to *structured output*, which is
 similar to the traditional byte-based stdout, but preserves all internal
 structures of aribitrary Elvish values. The most fundamental command that does
 this is `put`:
@@ -446,8 +446,8 @@ constructing a list or using rest variables:
 As of writing, Elvish is neither stable nor complete. The builtin libraries
 still have missing pieces, the package manager is in its early days, and things
 like a type system and macros have been proposed and considered, but not yet
-worked on. Deciding best practices for using feature _x_ can be a bit tricky
-when that feature _x_ doesn't yet exist!
+worked on. Deciding best practices for using feature *x* can be a bit tricky
+when that feature *x* doesn't yet exist!
 
 The current version of the document is what the lead developer of Elvish (@xiaq)
 has collected as best practices for writing Elvish code in early 2018, between

website/learn/faq.md

@@ -5,8 +5,8 @@
 The author of Elvish found the concept of a shell -- a programmable, interactive
 text interface for an OS -- to be simple yet powerful. However, he also felt
 that the more traditional shells, such as `bash` and `zsh`, didn't take it far
-enough. They all had _some_ programming capabilities, but they were only really
-sufficient for manipulating strings or lists of strings. They also had _some_
+enough. They all had *some* programming capabilities, but they were only really
+sufficient for manipulating strings or lists of strings. They also had *some*
 nice interactive features, such as tab completion, but more advanced UI features
 were either nonexistent, hidden behind obscure configuration options, or
 required external programs with suboptimal integration with the rest of the
@@ -56,7 +56,7 @@ Elvish is named after **elven** items in
 high quality. You can think of Elvish as an abbreviation of "elven shell".
 
 The name is not directly related to
-[Tolkien's Elvish languages](<https://en.wikipedia.org/wiki/Elvish_languages_(Middle-earth)>),
+[Tolkien's Elvish languages](<https://en.wikipedia.org/wiki/Elvish_languages\_(Middle-earth)>),
 but you're welcome to create something related to both Elvishes.
 
 Alternatively, Elvish is a backronym for "Expressive programming Language and

website/learn/fundamentals.md

@@ -332,8 +332,8 @@ Linux
 ```
 
 (If you are running macOS, `uname` will print `Darwin`, the
-[open-source core](<https://en.wikipedia.org/wiki/Darwin_(operating_system)>) of
-macOS.)
+[open-source core](<https://en.wikipedia.org/wiki/Darwin\_(operating_system)>)
+of macOS.)
 
 Let's try to integrate this information into our "hello" message. The Elvish
 command-line allows us to run multiple commands in a batch, as long as they are

website/learn/tour.md

@@ -17,7 +17,7 @@ If you are mainly interested in using Elvish interactively, jump directly to
 
 Many basic language features of Elvish are very familiar to traditional shells.
 A notable exception is control structures, covered [below](#control-structures)
-in the _advanced language features_ section.
+in the *advanced language features* section.
 
 ## Comparison with bash
 
@@ -423,7 +423,7 @@ the following command shows details of the `elvish` binary:
 -rwxr-xr-x 1 xiaq users 7813495 Mar  2 21:32 /home/xiaq/go/bin/elvish
 ```
 
-**Note**: the same feature is usually known as _command substitution_ in
+**Note**: the same feature is usually known as *command substitution* in
 traditonal shells.
 
 Unlike traditional shells, Elvish only splits the output on newlines, not any
@@ -1017,7 +1017,7 @@ To execute a dynamic piece of code for side effect, use
 Due to Elvish's scoping rules, files executed using either of the mechanism
 above can't create new variables in the current namespace. For example,
 `eval 'var foo = bar'; echo $foo` won't work. However, the REPL's namespace
-_can_ be manipulated with [`edit:add-var`](../ref/edit.html#edit:add-var).
+*can* be manipulated with [`edit:add-var`](../ref/edit.html#edit:add-var).
 
 ## test
 

website/ref/builtin.md

@@ -97,7 +97,7 @@ in one of two ways:
     ▶ C
     ```
 
-1.  From an argument -- an iterable value:
+2.  From an argument -- an iterable value:
 
     ```elvish-transcript
     ~> count [lorem ipsum] # count number of elements in argument

website/ref/command.md

@@ -105,8 +105,8 @@ directories:
     [interactively](#using-elvish-interactively) (so can't be used to check the
     [RC file](#rc-file), for example).
 
--   `-deprecation-level n`: Show warnings for features deprecated as of
-    version 0._n_.
+-   `-deprecation-level n`: Show warnings for features deprecated as of version
+    0.*n*.
 
     In release builds, the default value matches the release version, and this
     flag is mainly useful for hiding newly introduced deprecation warnings. For
@@ -114,7 +114,7 @@ directories:
     `-deprecation-level 41` to hide deprecation warnings introduced in 0.42,
     before you have time to fix those warnings.
 
-    In HEAD builds, the default value matches the _previous_ release version,
+    In HEAD builds, the default value matches the *previous* release version,
     and this flag is mainly useful for previewing upcoming deprecations. For
     example, if you are running a HEAD version between the 0.42.0 release and
     0.43.0 release, you can use `-deprecation-level 43` to preview deprecations

website/ref/edit.md

@@ -7,7 +7,7 @@ The `edit:` module is the interface to the Elvish editor.
 Function usages are given in the same format as in the
 [reference for the builtin module](builtin.html).
 
-_This document is incomplete._
+*This document is incomplete.*
 
 # Overview
 
@@ -251,7 +251,7 @@ mode, not the target mode. For instance, if you want to be able to use
 set edit:insert:binding[Alt-l] = { edit:location:start }
 ```
 
-One tricky case is the history mode. You can press <kbd>▲&#xfe0e;</kbd> to start
+One tricky case is the history mode. You can press <kbd>▲︎</kbd> to start
 searching for history, and continue pressing it to search further. However, when
 the first press happens, the editor is in insert mode, while with subsequent
 presses, the editor is in history mode. Hence this binding actually relies on
@@ -407,7 +407,7 @@ of `variable`, `index`, `command`, `redir` or `argument`. If the
 `$edit:completion:matcher['']` is used.
 
 Elvish then calls the matcher with one argument -- the seed, and feeds the
-_text_ of all candidates to the input. The mather must output an identical
+*text* of all candidates to the input. The mather must output an identical
 number of booleans, indicating whether the candidate should be kept.
 
 As an example, the following code configures a prefix matcher for all completion
@@ -467,14 +467,14 @@ set edit:after-command = [{|m| echo 'command took '$m[duration]' seconds' }]
 
 Given the above hooks...
 
-1. Every time you accept a chunk of code (normally by pressing Enter)
-   `just read` is printed.
+1.  Every time you accept a chunk of code (normally by pressing Enter)
+    `just read` is printed.
 
-1. At the very beginning of an Elvish session, or after a chunk of code is
-   handled, `going to read` is printed.
+2.  At the very beginning of an Elvish session, or after a chunk of code is
+    handled, `going to read` is printed.
 
-1. After each non empty chunk of code is accepted and executed the string
-   "command took ... seconds` is output.
+3.  After each non empty chunk of code is accepted and executed the string
+    "command took ... seconds\` is output.
 
 ## Word types
 

website/ref/language.md

@@ -160,7 +160,7 @@ represents Unicode codepoints in hexadecimal):
 
     -   `\^?` represents DEL (U+007F).
 
-    -   `\c` followed by character _X_ is equivalent to `\^` followed by _X_.
+    -   `\c` followed by character *X* is equivalent to `\^` followed by *X*.
 
 An unsupported escape sequence results in a parse error.
 
@@ -226,7 +226,7 @@ string that parses to a number. Examples:
 
 -   In the string `世界`, each codepoint is encoded with three bytes. The first
     codepoint occupies byte 0 through 2, and the second occupies byte 3 through
-    5\. Hence valid indices are 0 and 3:
+    5. Hence valid indices are 0 and 3:
 
     ```elvish-transcript
     ~> put 世界[0]
@@ -729,7 +729,7 @@ Compilation error: variable $nonexistent not found
 ```
 
 Note that Elvish resolves all variables in a code chunk before starting to
-execute any of it; that is why the error message above says _compilation error_.
+execute any of it; that is why the error message above says *compilation error*.
 This can be more clearly observed in the following example:
 
 ```elvish-transcript
@@ -743,7 +743,7 @@ Compilation error: variable $nonexistent not found
 When a function literal refers to a variable in an outer scope, the function
 will keep that variable alive, even if that variable is the local variable of an
 outer function that function has returned. This is called
-[closure semantics](<https://en.wikipedia.org/wiki/Closure_(computer_programming)>),
+[closure semantics](<https://en.wikipedia.org/wiki/Closure\_(computer_programming)>),
 because the function literal "closes" over the environment it is defined in.
 
 In the following example, the `make-adder` function outputs two functions, both
@@ -2413,14 +2413,14 @@ from the module spec by taking the part after the last slash.
 Module specs fall into three categories that are resolved in the following
 order:
 
-1. **Relative**: These are [relative](#relative-imports) to the file containing
-   the `use` command.
+1.  **Relative**: These are [relative](#relative-imports) to the file containing
+    the `use` command.
 
-1. **User defined**: These match a [user defined module](#user-defined-modules)
-   in a [module search directory](command.html#module-search-directories).
+2.  **User defined**: These match a [user defined module](#user-defined-modules)
+    in a [module search directory](command.html#module-search-directories).
 
-1. **Pre-defined**: These match the name of a
-   [pre-defined module](#pre-defined-modules), such as `math` or `str`.
+3.  **Pre-defined**: These match the name of a
+    [pre-defined module](#pre-defined-modules), such as `math` or `str`.
 
 If a module spec doesn't match any of the above a "no such module"
 [exception](#exception) is raised.
@@ -2439,16 +2439,26 @@ Elvish's standard library provides the following pre-defined modules that can be
 imported by the `use` command:
 
 -   [builtin](builtin.html)
+
 -   [edit](edit.html): only available in interactive mode. As a special case it
     does not need importing via `use`, but this may change in the future.
+
 -   [epm](epm.html)
+
 -   [math](math.html)
+
 -   [path](path.html)
+
 -   [platform](platform.html)
+
 -   [re](re.html)
+
 -   [readline-binding](readline-binding.html)
+
 -   [store](store.html)
+
 -   [str](str.html)
+
 -   [unix](unix.html): only available on UNIX-like platforms (see
     [`$platform:is-unix`](platform.html#platform:is-unix))