unisonweb / unison

A friendly programming language from the future
https://unison-lang.org
Other
5.81k stars 271 forks source link

Doc code block without a leading blank line interpreted as inline sample #5367

Open ceedubs opened 1 month ago

ceedubs commented 1 month ago

Describe and demonstrate the bug

If you omit a blank line before a triple-backtick code block, then it gets interpreted as a double-backtick inline code sample.

I don't know Markdown well enough to know whether this is a proper bug or just a consequence of Markdown, but it almost certainly isn't what the user intended in their doc.

Input:

```ucm
fresh/main> lib.install @unison/base

This doc has a triple backtick section that parses as a code sample.

doc1 = {{
# Examples

39 + 3


}}
fresh/main> add doc1
fresh/main> view doc1

This doc lacks a newline between the heading and the code sample, so the sample is not interpreted as a code block.

doc2 = {{
# Examples

39 + 3


}}
fresh/main> add doc2
fresh/main> view doc2

Output:
fresh/main> lib.install @unison/base

  Downloaded 24 entities.

  I installed @unison/base/releases/3.20.0 as
  unison_base_3_20_0.

This doc has a triple backtick section that parses as a code sample.

doc1 = {{
# Examples

39 + 3


}}

  Loading changes detected in scratch.u.

  I found and typechecked these definitions in scratch.u. If you
  do an `add` or `update`, here's how your codebase would
  change:

    ⍟ These new definitions are ok to `add`:

      doc1 : Doc
fresh/main> add doc1

  ⍟ I've added these definitions:

    doc1 : Doc

fresh/main> view doc1

  doc1 : Doc
  doc1 =
    use Nat +
    {{
    # Examples
  39 + 3
  ```
}}
This doc lacks a newline between the heading and the code sample, so the sample is not interpreted as a code block.

```` unison
doc2 = {{
# Examples

39 + 3


}}

  Loading changes detected in scratch.u.

  I found and typechecked these definitions in scratch.u. If you
  do an `add` or `update`, here's how your codebase would
  change:

    ⍟ These new definitions are ok to `add`:

      doc2 : Doc
fresh/main> add doc2

  ⍟ I've added these definitions:

    doc2 : Doc

fresh/main> view doc2

  doc2 : Doc
  doc2 =
    use Nat +
    {{
    # Examples `` 39 + 3 ``

    }}


**Screenshots**
If applicable, add screenshots to help explain your problem.

**Environment (please complete the following information):**
 - `ucm --version` c057942cf