Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/blog: support Markdown #33955

Closed
andybons opened this issue Aug 29, 2019 · 19 comments
Closed

x/blog: support Markdown #33955

andybons opened this issue Aug 29, 2019 · 19 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@andybons
Copy link
Member

If an article has an .md extension, it should render using a Markdown parser. We don’t have to go through the trouble of converting all articles over, but new ones should be in a more broadly supported format.

Perhaps using https://github.com/russross/blackfriday along with https://github.com/microcosm-cc/bluemonday to sanitize content.

@julieqiu with thoughts on Markdown libraries and sanitation 🚮

@andybons andybons added help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Aug 29, 2019
@andybons andybons added this to the Unreleased milestone Aug 29, 2019
@yu-chenxi
Copy link

I think it is a very good idea!

@smasher164
Copy link
Member

Would articles written in the Markdown format still support runnable code snippets? If so, one option is to implement a custom rendering engine for blackfriday that interprets snippets like the following as runnable.

```play
```

/cc @dmitshur since he's written a renderer for blackfriday before.

@ruzaikr
Copy link

ruzaikr commented Dec 9, 2019

I'd love to try this issue :) Pls assign it to me

@rsc
Copy link
Contributor

rsc commented Mar 11, 2020

I have a draft of this working, although the extension is unchanged. CLs to follow shortly.

@rsc rsc self-assigned this Mar 11, 2020
@rsc rsc removed the help wanted label Mar 11, 2020
@gopherbot
Copy link

Change https://golang.org/cl/222839 mentions this issue: content: wrap long lines using new program wrap.go

@gopherbot
Copy link

Change https://golang.org/cl/222841 mentions this issue: content: make spacing consistent + remove comments

@gopherbot
Copy link

Change https://golang.org/cl/222837 mentions this issue: content/company-questionnaire2018: remove UTF BOM and CR LF line endings

@gopherbot
Copy link

Change https://golang.org/cl/222840 mentions this issue: content: use tabs consistently for code blocks + indentation

@gopherbot
Copy link

Change https://golang.org/cl/222842 mentions this issue: content/gouk15: add a few more line breaks

@gopherbot
Copy link

Change https://golang.org/cl/222838 mentions this issue: content: fix some markup typos & mistakes

@gopherbot
Copy link

Change https://golang.org/cl/222846 mentions this issue: present: accept Markdown in present files

@gopherbot
Copy link

Change https://golang.org/cl/222844 mentions this issue: present: improve error for bad author block

@gopherbot
Copy link

Change https://golang.org/cl/222843 mentions this issue: present: allow line-wrapping of bullet list items

@gopherbot
Copy link

Change https://golang.org/cl/222845 mentions this issue: present: record info in AST for reproducing present inputs

@gopherbot
Copy link

Change https://golang.org/cl/222847 mentions this issue: cmd/present2md: add command to convert legacy present to Markdown-enabled present

@gopherbot
Copy link

Change https://golang.org/cl/222848 mentions this issue: content: convert to Markdown-enabled present inputs

gopherbot pushed a commit to golang/blog that referenced this issue Mar 11, 2020
For golang/go#33955.

Change-Id: Iecef7537016b629311f67c42500e614ba60b107c
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222837
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
gopherbot pushed a commit to golang/blog that referenced this issue Mar 11, 2020
For golang/go#33955.

Change-Id: I92c3c896055ed1baae34b0d85539068e6221ad38
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222838
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
gopherbot pushed a commit to golang/blog that referenced this issue Mar 11, 2020
Wrapping long lines will make diffs easier to read
for the eventual conversion to Markdown.

For golang/go#33955.

Change-Id: Ibcc1b5a84ccc9144b5fcdc9266f2da3e2cf3c5a3
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222839
Reviewed-by: Ian Lance Taylor <iant@golang.org>
gopherbot pushed a commit to golang/blog that referenced this issue Mar 11, 2020
A few articles used four spaces instead.
The present format will convert to four spaces for indentation on its own; use tabs.
The present format does not care what indentation is used, but use tabs everywhere for consistency.

For golang/go#33955.

Change-Id: I2bab8aa72fa2f68d48fb833b7317f87d7624a05f
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222840
Reviewed-by: Ian Lance Taylor <iant@golang.org>
gopherbot pushed a commit to golang/blog that referenced this issue Mar 11, 2020
Remove repeated blank lines, trailing spaces, trailing blank lines
Remove comments from survey2018.article (only article using them).
Remove blank lines between successive ".commands".

For golang/go#33955.

Change-Id: I90cae37a859a8e39549520569d5f10bc455415d3
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222841
Reviewed-by: Ian Lance Taylor <iant@golang.org>
gopherbot pushed a commit to golang/blog that referenced this issue Mar 11, 2020
Also one missing "by".
This will make Markdown diffs sync better.
Otherwise there's a rewrite on nearly every line
and diff loses track of what matches what.

For golang/go#33955.

Change-Id: I65391a4c768d925797181af1e054373d38510600
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222842
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
gopherbot pushed a commit to golang/tools that referenced this issue Mar 13, 2020
This is not strictly necessary, but being able to wrap these long lines
helps make the diffs for the Markdown conversion of old files easier to read.

The wrapping of the blog is in CL 222839.

For golang/go#33955.

Change-Id: I26c3f8db6b137c194f03b2538f221aa4fc3f2324
Reviewed-on: https://go-review.googlesource.com/c/tools/+/222843
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
gopherbot pushed a commit to golang/tools that referenced this issue Mar 13, 2020
I forgot to put in a section heading and every line
containing a colon in the text got parsed as a URL,
failing and printing errors. It took a while to find
where they were coming from.

For golang/go#33955.

Change-Id: Ibbc41a8446c292f6ab363829cf31fe594152e42d
Reviewed-on: https://go-review.googlesource.com/c/tools/+/222844
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
gopherbot pushed a commit to golang/tools that referenced this issue Mar 13, 2020
Commands like .code now have a TemplateCmd method
that returns the original command.

The Text struct now has a Raw field set when Pre==true.
It contains the original indented text, without the tab "fixing".

This helps building tooling that reformats or rewrites present files.

For golang/go#33955.

Change-Id: Ieb036e8b509a4531d120c597b19f2158306a5352
Reviewed-on: https://go-review.googlesource.com/c/tools/+/222845
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
gopherbot pushed a commit to golang/tools that referenced this issue Mar 13, 2020
Markdown is enabled by starting the title with "# ".
See the new documentation in present/doc.go for details.

For golang/go#33955.

Change-Id: I04ef2aa2cf253bdf48910c5674d679a482ffa33f
Reviewed-on: https://go-review.googlesource.com/c/tools/+/222846
Reviewed-by: Rob Pike <r@golang.org>
gopherbot pushed a commit to golang/tools that referenced this issue Mar 13, 2020
…bled present

Accepting Markdown in present is nice, but the job isn't done unless we
actually convert all our existing blog files to the new format. Otherwise we
have two different kinds of files to understand when working in that
directory. This tool lets us mechanically convert all the existing blog articles.

For golang/go#33955.

Change-Id: If8a8dd90eefa171f422644134d0571e2abe4c7cb
Reviewed-on: https://go-review.googlesource.com/c/tools/+/222847
Reviewed-by: Rob Pike <r@golang.org>
gopherbot pushed a commit to golang/blog that referenced this issue Mar 17, 2020
Converted blog to Markdown-enabled present (CL 222846)
using present2md (CL 222847).

For golang/go#33955.

Change-Id: Ib39fa1ddd9a46f9c7a62a2ca7b96e117635553e8
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222848
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@gopherbot
Copy link

Change https://golang.org/cl/231817 mentions this issue: content/constants: fix display of two backquote characters

gopherbot pushed a commit to golang/blog that referenced this issue May 5, 2020
Two backquote characters were expressed as 6 consecutive backquotes in
the legacy article format. That unusual sequence didn't translate well
into the new Markdown article format in CL 222848.
Replace it with simple HTML, since this is hard to express in Markdown.

For golang/go#33955.

Change-Id: I575aa89c9f9104de694d9a8dad4ca103cc4c1567
Reviewed-on: https://go-review.googlesource.com/c/blog/+/231817
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
@dmitshur
Copy link
Contributor

dmitshur commented May 8, 2020

This has been implemented via the aforementioned CLs. Closing.

Please re-open or file a new issue if there's something more to do here.

@gopherbot
Copy link

Change https://golang.org/cl/245017 mentions this issue: content: fix code block in Publishing Go Modules article

gopherbot pushed a commit to golang/blog that referenced this issue Jul 27, 2020
When indentation is used to create a code block immediately following
a list, Markdown syntax is ambiguous: it can be interpreted as another
text paragraph belonging to the last list entry, or as a standalone
code block.

The original behavior in CL 197637 made this unambiguously a code block
because the present format did not support lists. This changed when the
article was converted to use Markdown syntax in CL 222848.

Start using a fenced code block instead of indentation to resolve the
Markdown ambiguity and restore original behavior.

For golang/go#33955.

Change-Id: I9537bc72d7a32f90592942591b2688fb2f26c452
Reviewed-on: https://go-review.googlesource.com/c/blog/+/245017
Reviewed-by: Jean de Klerk <deklerk@google.com>
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
…line endings

For golang/go#33955.

Change-Id: Iecef7537016b629311f67c42500e614ba60b107c
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222837
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
X-Blog-Commit: f10b036ecb1362ffb4428bd9e02a99da4e7189a4
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
For golang/go#33955.

Change-Id: I92c3c896055ed1baae34b0d85539068e6221ad38
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222838
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
X-Blog-Commit: 0b4fcd39865e575704b5928c9a8f1cd21e18e8b2
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
Wrapping long lines will make diffs easier to read
for the eventual conversion to Markdown.

For golang/go#33955.

Change-Id: Ibcc1b5a84ccc9144b5fcdc9266f2da3e2cf3c5a3
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222839
Reviewed-by: Ian Lance Taylor <iant@golang.org>
X-Blog-Commit: 482079d678d84e207dd9ae63266c4bd4e653886b
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
A few articles used four spaces instead.
The present format will convert to four spaces for indentation on its own; use tabs.
The present format does not care what indentation is used, but use tabs everywhere for consistency.

For golang/go#33955.

Change-Id: I2bab8aa72fa2f68d48fb833b7317f87d7624a05f
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222840
Reviewed-by: Ian Lance Taylor <iant@golang.org>
X-Blog-Commit: 9dd3d9b97af3dba2bd18f1a5e18bd8e8edf78962
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
Remove repeated blank lines, trailing spaces, trailing blank lines
Remove comments from survey2018.article (only article using them).
Remove blank lines between successive ".commands".

For golang/go#33955.

Change-Id: I90cae37a859a8e39549520569d5f10bc455415d3
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222841
Reviewed-by: Ian Lance Taylor <iant@golang.org>
X-Blog-Commit: 7fd29cb024126de10a90c54427e050e7928c54b4
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
Also one missing "by".
This will make Markdown diffs sync better.
Otherwise there's a rewrite on nearly every line
and diff loses track of what matches what.

For golang/go#33955.

Change-Id: I65391a4c768d925797181af1e054373d38510600
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222842
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
X-Blog-Commit: 53cf23be3ddec2153847b84f09a9fce04bafa779
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
Converted blog to Markdown-enabled present (CL 222846)
using present2md (CL 222847).

For golang/go#33955.

Change-Id: Ib39fa1ddd9a46f9c7a62a2ca7b96e117635553e8
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222848
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
X-Blog-Commit: af5018f64e406aaa646dae066f28de57321ea5ce
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
Two backquote characters were expressed as 6 consecutive backquotes in
the legacy article format. That unusual sequence didn't translate well
into the new Markdown article format in CL 222848.
Replace it with simple HTML, since this is hard to express in Markdown.

For golang/go#33955.

Change-Id: I575aa89c9f9104de694d9a8dad4ca103cc4c1567
Reviewed-on: https://go-review.googlesource.com/c/blog/+/231817
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
X-Blog-Commit: 10cc6f575bc85cafbda92aa7030a8e5c6e486dfe
gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
When indentation is used to create a code block immediately following
a list, Markdown syntax is ambiguous: it can be interpreted as another
text paragraph belonging to the last list entry, or as a standalone
code block.

The original behavior in CL 197637 made this unambiguously a code block
because the present format did not support lists. This changed when the
article was converted to use Markdown syntax in CL 222848.

Start using a fenced code block instead of indentation to resolve the
Markdown ambiguity and restore original behavior.

For golang/go#33955.

Change-Id: I9537bc72d7a32f90592942591b2688fb2f26c452
Reviewed-on: https://go-review.googlesource.com/c/blog/+/245017
Reviewed-by: Jean de Klerk <deklerk@google.com>
X-Blog-Commit: fb994f42d8394e948c3d58235828e9ed5f2f3077
@golang golang locked and limited conversation to collaborators Jul 27, 2021
@rsc rsc removed their assignment Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

7 participants