search

rusefi / rusefi_documentation

User documentation for rusEFI engine control unit
GNU General Public License v3.0
23 stars 31 forks source link

mkdocs: auto-detect URLs on wiki3 #188

Closed rusefillc closed 1 year ago

rusefillc commented 2 years ago

https://github.com/rusefi/rusefi/wiki/Release-Process renders links as links

https://wiki.rusefi.com/Release-Process/ does not :(

is this something we can improve globally or would I have to use full syntax?

rusefillc commented 2 years ago

is this something https://github.com/orbikm/mkdocs-ezlinks-plugin is supposed to be helping with?

chuckwagoncomputing commented 2 years ago

No I don't think so. I suppose we could manually change them all to the correct URL format, as that would be backwards compatible with Github wiki. Maybe I'll write a script to do that.

chuckwagoncomputing commented 2 years ago

Massive effort ongoing: https://github.com/chuckwagoncomputing/rusefi_documentation/tree/linkify

chuckwagoncomputing commented 2 years ago

I think all of these are fixed. The title of this issue is "auto-detect URLs", which as far as I can tell isn't possible currently. I suppose it would be possible to write a MkDocs plugin that would do that, but I think it's better to manually make URLs links, and give them a proper title.

rusefillc commented 1 year ago

Status update:

@chuckwagoncomputing has explicitly converted all URLs into full blown URL syntax like https://github.com/chuckwagoncomputing/rusefi_documentation/commit/a6c27028f406ee32294e3fe43f1cf32d8edac642

it sounds like the proposal is to just always to use explicit syntax which is nasty but gets us forward

rusefillc commented 1 year ago

Reopening since I think it's far from done

Problem: I am a lazy human and I've created new content on wiki2-technical https://github.com/rusefi/rusefi_documentation/blob/master/Gen-4-LS.md note how links are nicely rendered as URL

and now same new content on wiki3 https://wiki.rusefi.com/Gen-4-LS/

note how links are not URLs

I really do not like working hard. We need automation for edits on wiki2-technical or wiki2-human to be rendered as URLs on wiki3

chuckwagoncomputing commented 1 year ago
  1. "Automatic Links" are not part of the Markdown standard, they're an additional thing Github has done.
  2. Bare URL links are ugly and uncivilized
  3. Don't be lazy
rusefillc commented 1 year ago
  1. Don't be lazy

I hope to stay in human form for 30ish more years, there is no way I can take manual self-control of URL approach

if we are unable to automate the translation we have to at least automated detection: there should be at least an email or a URL where all "bad" links are mentioned so that manual human replacement could be done based on the auto-generated problem report and not just by manual review

mi-hol commented 1 year ago
  1. "Automatic Links" are not part of the Markdown standard, they're an additional thing Github has done.

GitHub's user experience for editors is therefore much better than what a later wiki user gets to see. From my view its a major gap that needs to be closed in order to get better rusEFI community involvement in documentation

mi-hol commented 1 year ago

I found a very similar issue with a solution in https://github.com/community/community/discussions/22154#discussioncomment-3235674 Would mkdoc perhaps have an option for GitHub Flavoured Markdown?

rusefillc commented 1 year ago

Also question if we shall move to https://kramdown.gettalong.org/ engine ? :)

mi-hol commented 1 year ago

move to https://kramdown.gettalong.org/ engine

would have been my second question, in case first is answered with a "no"

chuckwagoncomputing commented 1 year ago

After some more research, it seems that Mkdocs can pass plugins to Python-markdown, so maybe a combination of https://github.com/selcuk/markdown-urlify and https://github.com/Python-Markdown/github-links could be made to work.

And Kramdown is just a markdown engine, it only does fraction of what Mkdocs does.

mi-hol commented 1 year ago

Mkdocs can pass plugins to Python-markdown, so maybe a combination of https://github.com/selcuk/markdown-urlify and https://github.com/Python-Markdown/github-links could be made to work.

Any suggestion on how to try this? I'm a noob regarding Mkdocs unfortunately

chuckwagoncomputing commented 1 year ago

I'm a noob as well. The mkdocs config is here. The documentation for the markdown_extension option is here.