I'm using Jekyll on Github, and I wonder whether there's a way to link to a section within a page. Say I have a section like
## Section 1 ##
section content
and later in the same page I want to link to this section. I've found how to link to another page within the blog and do footnotes, but not this.
As a note, I use markdown: kramdown in my _config.yml
kramdown supports the automatic generation of header IDs if the option
auto_ids is set to true (which is the default). This is done by
converting the untransformed, i.e. plain, header text
So in the above example ## Section 1 ##, it would generate the following id: id="section-1", then the anchor is linked to via the A element:
Section One
Or in plain kramdown/markdown: [Section 1](#section-1)
It seems that this has been changed to #heading-section-1 (checking on Jekyll 3.7.3 right now).
As a way to figure this out on your own, you can inspect the element and see the id being used on the rendered page.
I found a nice repository that helps add anchors to all headers in three simple steps.
From docs:
Download the anchor_headings.html file from the master branch
Toss that file in your _includes folder
Where you typically would put {{ content }} in your layout,
you would instead use this Liquid tag to output your page's content:
{% include anchor_headings.html html=content anchorBody="#" %}
As result you will see:
Which is easy to customize.
If the section of the page you want to jump to is not a section heading, then this accepted answer didn't work for me. The following worked for me:
[jump](#final-solution)
<div id="final-solution"></div>
Related
I'm trying to make a GitHub page. At the beginning, I use GitHub generator. I included Gemfile and _config.yml to generate SEO tag and it works as expected. The generated site will include the following section.
<!-- Begin Jekyll SEO tag v2.6.1 -->
<meta ...
<!-- End Jekyll SEO tag -->
Now, I've just updated my site to the new one using HTML template from HTML5 UP. It's up and run normally, however, I cannot find a way to make Jekyll generate SEO tag for my index.html file. I've tried to add triple dashes (front matter) to my index.html on the first line.
---
---
<!DOCTYPE HTML>
<!-- Other code below -->
The thing is, it partially break the site (page isn't rendered properly). Therefore, I've to copy/paste the generated tag and add them manually to my code. Is there a way to make Jekyll properly create SEO tags for my site? Or did my misunderstand something very basic here?
To be clear, I've very limited knowledge in web development, that's why I use a template in the first place. Here is my page in case it helps clarify the question https://hunghvu.github.io/ and here is its GitHub repository incase you want to know the file structure.
Update
(09/30)
I attempted to turn the index.html file into index.md while still keeping all the code (plus the tripled dashes). In a sense, it works. The page is generated, but still, it's not rendered properly as when I use html format. I'm aware that the way to actually build site using Jekyll is much different, but that does not answer my question.
In case it is necessary to show what I mean by saying "not properly rendered", I will update this question later on.
(09/31)
The picture below is how my page looks like when I add front matter and {% seo %}. Notice that when I first go to the page, the side bar is already in SOME OTHER WORK, or last section. It should be on the WELCOME. The WELCOME section is not rendered and sidebar functionality is broken.
Problem
GitHub pages gem is not included in your project, therefore GitHub is not running Jekyll build. Furthermore, you have nothing specified in your front matter. You also have no layout.
Solution
Include gem "github-pages", "~> VERSION", group: :jekyll_plugins in your Gemfile.
Notes
Consider using front matter and creating a layout file _layouts/default.html and moving everything except what’s in body (including SEO)to the layout file. The index.html should extend the layout by specifying layout property in front matter.
References
Front Matter: https://jekyllrb.com/docs/front-matter/
GitHub (step 9): https://docs.github.com/en/free-pro-team#latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll
Is it possible to set a permalink to an external site within YAML front matter? I am currently using Jekyll, and I am not finding any information using my Google-Fu.
---
layout: full-width
title: TEST
permalink: https://somethingexternal.example
---
Can permalink break out of it's context and head to somethingexternal? I just want the TEST link to appear on the home page, but when clicked, to go to somethingexternal.example.
[edit]: What happens is that it prepends the webroot to the site, which is the expected behavior. So it ends up like:
mysite.blah/https://somethingexternal...
I just need to break out of it, so that it only goes to the external site. I don't know if permalink can do that, though.
Using permalinks for an external link won't work, permalinks aren't for that.
What you are looking for is to define a custom URL in front matter and then access it's value from the page like this:
---
othersite: http://example.com
---
visit other site
md file with a link to Folder/file.md
When jekyll generates the index the link to the file is still folder/file.md and so doesn't connect to the generated file.html. Can jekyll replace links in markdown with their corresponding html files?
I really want to to maintain my folder structure (7 or so subfolders, each with 3 markdown files).
The answer since December 2016 is to use the jekyll-relative-links plugin.
It is a white-listed plugin if you are hosting on GitHub pages so you probably already have it.
If you are not using GitHub pages you will need the following installation instructions (from the README):
1.Add the following to your site's Gemfile:
gem 'jekyll-relative-links'
2.Add the following to your site's config file:
gems:
- jekyll-relative-links
The tag you're looking for is {% link %} and it arrived in 2016.
If you had {% link _funkyCollection/banjo.md %} it would generate the right path to the output file funkyCollection/banjo.html, or funkyCollection/banjo/index.html, or whatever, wherever it ends up being.
This is what I did to solve this problem with jekyll 3.8.5.
For link in root directory: /file.md
---
layout: page
title: Root File
permalink: /file/
---
This file is in root directory.
For link in subdirectory: /folder/file.md
---
layout: page
title: SubDir File
permalink: /folder/file/
---
This file is in sub-directory.
Now to link these file:
[Root File]({{site.baseurl}}/file/))
[Sub Dir File]({{site.baseurl}}/folder/file/)
Hope this helps someone.
i've written a simple plugin to solve this. put this in _plugins/, and make links refer to the *.md files (so github rendering linking works); if you build it with jekyll (when you are able to run plugins) the links are changed to *.html. since github doesn't run plugins, this isn't applied.
module ChangeLocalMdLinksToHtml
class Generator < Jekyll::Generator
def generate(site)
site.pages.each { |p| rewrite_links(site, p) }
end
def rewrite_links(site, page)
page.content = page.content.gsub(/(\[[^\]]*\]\([^:\)]*)\.md\)/, '\1.html)')
end
end
end
it's not perfect (i'm sure you could fool the regex) but it has been good enough for my purpose.
A Folder/file.md page will result in creation of a _site/Folder/file.html page.
So when your link to this page it's [Link to page]({{site.baseurl}}/Folder/file.html) not [Link to page]({{site.baseurl}}/Folder/file.md).
Jekyll will never rewrite file.md to file.html in url. So you have to set your links targets yourself to the resulting page.url which is usually a html file but can be css, je, json, ...
If you use permalink: /folder/folder/ in any file.md, it will generate a /folder/folder/index.html file which can be reached with [Link to page]({{site.baseurl}}/folder/folder/)
I've run into this and written a basic Jekyll/Kramdown plugin. It's less likely to break than the regular expression approach.
As long as your link doesn't start with http:// or something like it, and ends with .md, it will convert links to their lowercased and hyphenated names.
Of course, you could always modify the behavior to fit your needs.
I'm using Jekyll to make a site that makes frequent use of kramdown's attribute list definitions. However the only way I can make this work right now is to include all of the definitions in every page e.g.
{:def1: ...}
{:def2: ...}
{:def3: ...}
This seems really smelly to me since if I want to change a definition, I need to do so in every single page. Ugh.
Is it possible to put these definitions somewhere where they will be included in every page? I tried putting them in a layout but it seems that Jekyll won't parse markdown in layouts.
I'm also open to alternatives to ALDs if this is not the right way to go about things.
If you want to add definitions to your posts, you can also create an .md file in your _includes folder with definitions like:
*[def1]: ...
*[def2]: ...
And then you can add this file to every post using {% include definitions.md %}.
It shouldn't be in the _layouts folder. Try keeping it in the _includes folder and then include it with this tag {% include definitions.html %}
I have created a gh-pages branch for a project that I am working on at GitHub.
I use Sublime text to author the website locally and my problem is that when this is pushed to GitHub, all the links to javascrips, images, and css files are invalid.
For instance, I have this in my head section.
<link href="assets/css/common.css" rel="stylesheet">
This works great locally, but it does not work from GitHub as the links are not resolved using the repository name as part of the URL.
It asks for:
http://[user].github.io/assets/css/common.css
when it should have been asking for:
http://[user].github.io/[repo]/assets/css/common.css.
I could of course put the repo name as part of the URL, but that would prevent my site to work locally during development.
Any idea how to deal with this?
You'll need to use Jekyll.
Copying verbatim from the relevant documentation:
Sometimes it’s nice to preview your Jekyll site before you push your
gh-pages branch to GitHub. However, the subdirectory-like URL
structure GitHub uses for Project Pages complicates the proper
resolution of URLs. Here is an approach to utilizing the GitHub
Project Page URL structure (username.github.io/project-name/) whilst
maintaining the ability to preview your Jekyll site locally.
In _config.yml, set the baseurl option to /project-name – note the leading slash and the absence of a trailing slash.
When referencing JS or CSS files, do it like this: {{ site.baseurl}}/path/to/css.css – note the slash immediately following
the variable (just before “path”).
When doing permalinks or internal links, do it like this: {{ site.baseurl }}{{ post.url }} – note that there is no slash between
the two variables.
Finally, if you’d like to preview your site before committing/deploying using jekyll serve, be sure to pass an empty
string to the --baseurl option, so that you can view everything at
localhost:4000 normally (without /project-name at the beginning):
jekyll serve --baseurl ''
This way you can preview your site locally from the site root on
localhost, but when GitHub generates your pages from the gh-pages
branch all the URLs will start with /project-name and resolve
properly.
(Apparently someone figured this out only a few months ago.)
Which browser are you using? Are you sure that this happens? Because it shouldn't. If you include a relative URL in a link, it will get resolved relative to the URL of the document that contains the link. In other words, when you include
<link href="assets/css/common.css" rel="stylesheet">
in an HTML document at http://www.foo.com/bar/doc.html, the link to assets/css/common.css will get resolved by appending it to the prefix of the URL of the HTML document without the last part of the path (without doc.html), i.e. the link will resolve to http://www.foo.com/bar/assets/css/common.css, not to http://www.foo.com/assets/css/common.css as you claim.
For example, view the source of the Twitter Bootstrap webpage: http://twitter.github.io/bootstrap/. Notice the style links at the top, specified as <link href="assets/css/bootstrap.css" rel="stylesheet">. That link correctly resolves to http://twitter.github.io/bootstrap/assets/css/bootstrap.css, i.e. it does include the repo name.
You could just put this
<base href="/[repo]/">
inside of the <head> tag, and it solves the problem.
You could also improve this solution by setting:
<base href="{{site.baseurl}}" />
and then set site.baseurl to empty string for the local testing.
This should not be an issue anymore in Dec. 2016, 3 and an half years later.
See "Relative links for GitHub pages", published by Ben Balter:
You've been able to use relative links when authoring Markdown on GitHub.com for a while.
(that is from January 2013)
Now, those links will continue to work when published via GitHub Pages.
If you have a Markdown file in your repository at docs/page.md, and you want to link from that file to docs/another-page.md, you can do so with the following markup:
[a relative link](another-page.md)
When you view the source file on GitHub.com, the relative link will continue to work, as it has before, but now, when you publish that file using GitHub Pages, the link will be silently translated to docs/another-page.html to match the target page's published URL.
Under the hood, we're using the open source Jekyll Relative Links plugin, which is activated by default for all builds.
Relative links on GitHub Pages also take into account custom permalinks (e.g., permalink: /docs/page/) in a file's YAML front matter, as well as prepend project pages' base URL as appropriate, ensuring links continue to work in any context.
And don't forget that since August 2016, you can publish your pages right from the master branch (not always the gh-pages branch)
And since Dec. 2016, you don't even need Jekyll or index.md. Simple markdown files are enough.
It seems that Github Pages is not very responsive. Though it makes new files available immediately, modified files would not appear immediately due to caching or something.
After waiting 15 minutes or so, everything is fine.
Another option is to create a new repo specifically for the github.io webpages. If you name the repo as [user].github.io on github then it will be published at https://[user].github.io and you can avoid having the repo name in the URL path completely. Obviously the downside is that you can only have 1 repo like this per github user, so it may not suit your needs, I'm not sure.
The best option is now the relative_url filter:
<link href="{{ '/assets/css/common.css' | relative_url }}" rel="stylesheet">