Githublink helper #1398

SvenDowideit · 2015-09-03T05:12:40Z

This PR changes the way that markdown Links are rendered, by converting source level links like /docs/article/networking.md into rendered output links like /article/networking/. (with the implicit index.html).

This link resolution is done either as an absolute path, or relative to the currently rendered page.

For example, when rendering /docs/foo/hex.md into /foo/hex/index.html, a markdown link [test](test.md) would be linked to the html output path that will be made for /docs/foo/test.md - ie /foo/test/index.html, as its at the same filesystem level has hex.md (so long as it exists - if not, you get an error message and the link will be to the original input text).

The intention is that if you enable [blackfriday] GithubLinking=true in your config.toml, then all links that work when viewing the rendered source markdown files in the github repository will also link up the same way in the Hugo rendered html.

bep · 2015-09-03T08:00:46Z

Is the motivation behind this to get links that works both when browsing on GitHub and building with hugo?

This would be cool, but in my head these links are incompatible -- the GitHub one points to a Markdown file, the Hugo variant links to a HTML fil, a build result.

SvenDowideit · 2015-09-03T12:03:14Z

yes, what we need is for Hugo to transform the .md file links ala github into the html links used in the html - that way, documents that are in a github repo can work both on github, and when published as html.

(we basically want our cake and to eat it :) ) and it turns out the code isn't complicated.

bep · 2015-09-04T22:27:31Z

code isn't complicated

Well, I have read it twice, and I do not understand it. A nice start would be to explain in common language how you are trying to solve this problem?

SvenDowideit · 2015-09-05T07:49:24Z

sorry :)

This code over-rides the blackfriday Link() rendering function to check the link URL against the markdown source paths known to Hugo. If githubLink() finds a match, it replaces the source file path with that path's html output url/permalink.

as the helpers - like context_rendering.go doesn't have direct access to the hugolib site data, I'm passing the site search and url as a closure that the render-er can use without breaking the clean separation too much.

moxiegirl · 2015-09-07T21:10:50Z

@bep What's your opinion of @SvenDowideit's comment? This is a feature we want and I think would be good for Hugo but if y'all aren't on board with the implementation better to know sooner than later.

@SvenDowideit looks like you plan to implement a flag. The flag isn't a boolean tho --- it is taking a dir value just looking at your TODO. What's the thinking here?

SvenDowideit · 2015-09-07T23:37:49Z

I'm thinking about adding a couple of flags - a boolean that toggles this github like relative linking functionality and some kind of project input path prefix to help deal with github links like /docs, github.com/spf13/hugo/docs.

I'm almost done with the exploratory phase of this change, and once we've made sure that it covers most of our needs, I'll start cleaning it up and writing docs for it so we can discuss merging.

bep · 2015-09-08T15:18:56Z

helpers/content.go

@@ -173,11 +173,12 @@ func GetHTMLRenderer(defaultFlags int, ctx *RenderingContext) blackfriday.Render
 	}

 	return &HugoHtmlRenderer{
-		blackfriday.HtmlRendererWithParameters(htmlFlags, "", "", renderParameters),
+		Dir:      ctx.Dir,


What is the dir used for?

ooo, its not anymore! - I've an update coming, but i need to forward port it from the my v0.14 fork.

bep · 2015-09-09T12:13:46Z

@moxiegirl I think this is a feature that many would want -- and thinking about it, it's a must for software documentation. And now the code starts to shape up, too. I like the change to the simple LinkResolver -- and I wonder if the config property also could be made more generic (how does this work with BitBucket?)

moxiegirl · 2015-09-10T00:02:42Z

@bep cool...@SvenDowideit can speak to Bitbuckt. I'm not sure what they are using for MD....Sven if you need me to find out...I worked with those guys and I can ask direct.

SvenDowideit · 2015-09-10T02:54:53Z

yup, I'll look into it :)

SvenDowideit · 2015-10-12T02:19:59Z

it looks like BitBucket's markdown rendering is very primitive - the examples they give are all using full absolute http:// style links - which hugo is already happy with.

I'm going to update this PR soon, and rename to something like source linking - @spf13 @bep @moxiegirl can you think of a more descriptive name?

moxiegirl · 2015-10-12T04:06:05Z

Maybe source-relative-links

bep · 2015-10-12T04:19:19Z

Maybe source-relative-links

That works.

SvenDowideit · 2015-10-12T22:50:32Z

@bep - I'm having trouble figuring out what I did break the tests :/

bep · 2015-10-13T06:49:44Z

.dockerignore

@@ -0,0 +1,2 @@
+Dockerfile


Would be easier to read the diffs without all this docker stuff checked in. Git has a concept of local ignore.

CLAassistant · 2015-11-03T12:22:54Z

All committers have accepted the CLA.

bep · 2015-11-09T07:08:07Z

If I grok go right, in both cases (Pages and Files), the information is stored in Site. SiteInfo contains a pointer to the arrays in Site. Until this PR, SiteInfo.Files wasn't being used or initialized - now it is.

This is now a pointer to a slice -- which I haven't seen before. It's perfectly valid Go syntax, but I'm not sure about the usefulness. It just means that it will crash harder when not initialized ... Pointers to arrays, on the other hand, is very handy.

SvenDowideit · 2015-11-11T13:08:07Z

oh duh, thanks (that has caught me out a few times) - we're initializing the slice pointer when we create the SiteInfo struct with Files: &s.Files,

mmm, ok, time to try to convince you :)

I think I'm copying what was done for SiteInfo.Pages - which is declared as a *Pages - which is defined in hugolib/page.go:type Pages []*Page

SvenDowideit · 2015-11-24T02:19:35Z

mmm, why am i getting build failures in a file I didn't modify?

commands/hugo.go:323: undefined: viper.WatchConfig

go build -v returned exit code 2

commands/hugo.go:324: undefined: viper.OnConfigChange Action failed: go build

rebasing, in case its resolved.

ala GitHub repository markdown for both md files and non-md files Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>

SvenDowideit · 2015-11-24T02:49:29Z

@spf13 @bep it looks like circleci isn't updating the viper dependency, so is failing.

bep · 2015-11-24T08:54:44Z

Looks like the trick in these situations is to "retry without cache".

SvenDowideit · 2015-11-24T09:06:15Z

awesome! merci :) and now to make it work using https://github.com/miekg/mmark too

spf13 · 2016-01-01T20:24:58Z

@SvenDowideit @moxiegirl sorry this was such a long time to get it to a merge. Thanks for the addition and the diligence around this. It's now merged as 0f6b334

moxiegirl · 2016-01-03T03:11:40Z

Thanks @spf13 Steve very much appreciate this. Hope it helps other folks.

SvenDowideit · 2016-01-04T06:10:56Z

@spf13 🎈 that's a very nice post-holiday present :)

uppity · 2016-03-02T14:09:03Z

Hi @SvenDowideit is there a zipped test site available? I have built Hugo from latest source and it doesn't work as I thought it would... however I may not be totally understanding its intended use so I wondered if there were some sample files. I am trying to just show an image which is in the same folder as my md file, should that work or?

![This is an image](./a.png)

fb551cc75 Update index.md 7af894857 Update index.md d235753ea Hugo 0.82.1 e03e72deb Merge branch 'temp0821' e62648961 Merge branch 'release-0.82.1' e1ab0f6eb releaser: Add release notes to /docs for release of 0.82.1 5d354c38d Replaced ``` code blocks with Code Toggler c9d065c20 Remove duplicate YAML keys (#1420) 8ae31e701 Add webp image encoding support 848f2af26 Update internal.md (#1407) c103a86a4 Fix `ref` shortcode example output (#1409) 9f8ba56dc Remove leading dot from where function KEY (#1419) 363251a51 Improve presentation of template lookup order (#1382) b73da986d Improve description of Page Resources (#1381) 4e0bb96d5 Rework robots.txt page (#1405) edf893e6f Update migrations.md (#1412) 450f1580b Add link to `site` function doc (#1417) cfffa6e6f Added one extension to the list (#1414) 05f1665a0 Update theme 5de0b1c6a Update theme 250e20552 Add hugo.IsExtended dea5e1fd7 Fix typo on merge function page (#1408) 1bbed2cf3 Update configuration.md be0b64a46 Omit ISO cbb5b8367 Fix `dateFormat` documentation 698f15466 Regenerate the docshelper f9a8a7cb6 Update multilingual.md a22dc6267 Fix grammar (#1398) eb98b0997 Fix pretty URL example (#1397) f4c4153dc Mention date var complementation in post scheduling (#1396) 17fae284c Fix resources.ExecuteAsTemplate argument order (#1394) 97e2c2abb Use code-toggle shortcode in `multilingual.md` (#1388) 3a84929bb Harmonize capitalization (#1393) 17f15daa6 fix file naming used in example (#1392) 5d97b6a18 Add slice syntax to sections permalinks config 00665b97b Improve description of `site.md` edcf5e3fc Fix example in `merge.md` f275ab778 Update postprocess.md 9593e3991 Fix file name 59bd9656f Update postprocess.md 1172fb6d0 Update to theNewDynamic repository (#1263) f5b5c1d2c Update Hugo container image 4f2e92f2a Adapt anchorize.md to Goldmark 98aa19073 Directly link to `highlight` shortcode (#1384) 4c75c2422 Fix header level f15c06f23 markdownify: add note about render-hooks and .RenderString (#1281) 69c82eb68 Remove Blackfriday reference from shortcode desc (#1380) 36de478df Update description of ignoreFiles config setting (#1377) 6337699d8 Remove "Authors" page from documentation (#1371) 35e73ca90 fix indent in example (#1372) d3f01f19a Remove opening body tag from header example (#1376) 341a5a7d8 Update index.md c9bfdbee6 Release 0.82.0 119644949 releaser: Add release notes to /docs for release of 0.82.0 32efaed78 docs: Regenerate docs helper dea5449a2 docs: Regen CLI docs eeab18fce Merge commit '81689af79901f0cdaff765cda6322dd4a9a7ccb3' d508a1259 Attributes for code fences should be placed after the lang indicator only c80905cef deps: Update to esbuild v0.9.0 95350eb79 Add support for Google Analytics v4 02d36f9bc Allow markdown attribute lists to be used in title render hooks 7df220a64 Merge commit '9d31f650da964a52f05fc27b7fb99cf3e09778cf' d80bf61b7 Fixes #7698. git-subtree-dir: docs git-subtree-split: fb551cc750faa83a1493b0e0d0898cd98ab74465

github-actions · 2022-02-24T01:57:09Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

bep reviewed Sep 8, 2015
View reviewed changes

This was referenced Sep 10, 2015

Add GitHub style code fence support to mmark. Fixes #1258. #1412

Closed

Images in markdown relative to content #1240

Closed

Support HTML comments frontmatter #1428

Closed

bep reviewed Oct 13, 2015
View reviewed changes

Source file based relative linking

fbcd1a5

ala GitHub repository markdown for both md files and non-md files Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>

spf13 closed this Jan 1, 2016

github-actions bot locked as resolved and limited conversation to collaborators Feb 24, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Githublink helper #1398

Githublink helper #1398

SvenDowideit commented Sep 3, 2015

bep commented Sep 3, 2015

SvenDowideit commented Sep 3, 2015

bep commented Sep 4, 2015

SvenDowideit commented Sep 5, 2015

moxiegirl commented Sep 7, 2015

SvenDowideit commented Sep 7, 2015

bep Sep 8, 2015

SvenDowideit Sep 8, 2015

bep commented Sep 9, 2015

moxiegirl commented Sep 10, 2015

SvenDowideit commented Sep 10, 2015

SvenDowideit commented Oct 12, 2015

moxiegirl commented Oct 12, 2015

bep commented Oct 12, 2015

SvenDowideit commented Oct 12, 2015

bep Oct 13, 2015

CLAassistant commented Nov 3, 2015

bep commented Nov 9, 2015

SvenDowideit commented Nov 11, 2015

SvenDowideit commented Nov 24, 2015

SvenDowideit commented Nov 24, 2015

bep commented Nov 24, 2015

SvenDowideit commented Nov 24, 2015

spf13 commented Jan 1, 2016

moxiegirl commented Jan 3, 2016

SvenDowideit commented Jan 4, 2016

uppity commented Mar 2, 2016

github-actions bot commented Feb 24, 2022

Githublink helper #1398

Githublink helper #1398

Conversation

SvenDowideit commented Sep 3, 2015

bep commented Sep 3, 2015

SvenDowideit commented Sep 3, 2015

bep commented Sep 4, 2015

SvenDowideit commented Sep 5, 2015

moxiegirl commented Sep 7, 2015

SvenDowideit commented Sep 7, 2015

bep Sep 8, 2015

Choose a reason for hiding this comment

SvenDowideit Sep 8, 2015

Choose a reason for hiding this comment

bep commented Sep 9, 2015

moxiegirl commented Sep 10, 2015

SvenDowideit commented Sep 10, 2015

SvenDowideit commented Oct 12, 2015

moxiegirl commented Oct 12, 2015

bep commented Oct 12, 2015

SvenDowideit commented Oct 12, 2015

bep Oct 13, 2015

Choose a reason for hiding this comment

CLAassistant commented Nov 3, 2015

bep commented Nov 9, 2015

SvenDowideit commented Nov 11, 2015

SvenDowideit commented Nov 24, 2015

SvenDowideit commented Nov 24, 2015

bep commented Nov 24, 2015

SvenDowideit commented Nov 24, 2015

spf13 commented Jan 1, 2016

moxiegirl commented Jan 3, 2016

SvenDowideit commented Jan 4, 2016

uppity commented Mar 2, 2016

github-actions bot commented Feb 24, 2022