Formatting fix - Githubissues

ponylang / pony-tutorial

:horse: Tutorial for the Pony programming language

http://tutorial.ponylang.io

BSD 2-Clause "Simplified" License

310 stars 111 forks source link

Formatting fix #427

Closed damon-kwok closed 4 years ago

damon-kwok commented 4 years ago

pony-tutorial formatting fix

damon-kwok commented 4 years ago

@SeanTAllen what about this?

SeanTAllen commented 4 years ago

@damon-kwok I haven't had a chance to review yet.

SeanTAllen commented 4 years ago

@damon-kwok there are a couple numbering fixes for lists. can you break those out into their own PR?

regarding the relref. i'm a little hesitant on those. if we are going to do, i'd like to have in their own PR. a couple questions... given how path specific those relrefs are , what is the advantage over the existing? I personally don't see any. And the special "must end in .md and _index.md"-ness makes me think it would be harder for new people coming in compared to the existing "using the relative url" approach.

I'm open to the relref switch but, what's the argument for the change? As I said, I don't see any advantage for how we are currently doing linking.

damon-kwok commented 4 years ago

@SeanTAllen relref is useful:

it can be checked at compile time.
It allows the generated website to be deployed without root path

SeanTAllen commented 4 years ago

@damon-kwok checked at compile time is a very good one.

i'm not sure what you mean by "deployed without root path". can you clarify "root path"?

SeanTAllen commented 4 years ago

@damon-kwok I'm generally ok with the change to relref to get compile time support. I wasn't aware it would error out if its a bad link (I might have known that once). If we are going to do that, I'd like to get all the internal links updated in a single PR. Before you start on that though get 1 or both of @EpicEric and @rhagenson to sign off on the change as well.

damon-kwok commented 4 years ago

@SeanTAllen

deployed to pony-tutorial.github.io , no problem.
deployed to https://damon-kwok.github.io/pony-tutorial, url-based link will unavailable. for example: [sugar] (/expressions/sugar.html) //It always link to: https://damon-kwok.github.io/expressions/sugar.html [sugar] ({{< relref "expressions/sugar.md" >}} ) //result：https://damon-kwok.github.io/pony-tutorial/expressions/sugar.html

SeanTAllen commented 4 years ago

@damon-kwok I see so you are saying it that you can set the root to something other than just the website more like https://website/sub-folder/

Not much of a win for us on that front, but the compile time checking seems like a good win.

As I said, let's ping @rhagenson and/or @EpicEric and get their feedback before proceeding but I'm good with the change (based on my limited knowledge) so long as there's a single PR that updates everything in the tutorial and contributing information for the tutorial is updated to explain that people need to use relref and how to use it.

EpicEric commented 4 years ago

I'm okay with this change as well, so long as it's in a single PR for the whole tutorial as Sean said.

Are we planning on enforcing this link style with a lint script or something to be run per PR?

SeanTAllen commented 4 years ago

@EpicEric I linter would be good. I'm not aware of any for hugo.

damon-kwok commented 4 years ago

@EpicEric What do I need to do?

damon-kwok commented 4 years ago

@rhagenson #428 #429