What do you want exactly?
I have a website in Hugo. However I have a peculiar situation.
Scientists and Electrical Engineers and others may have specific needs. For Eg: Having a single page that shows a simulation. Or in my case using webbluetooth and webusb that I have written from scratch in HTML, CSS and JS. Moreover these pages may be generated by custom scripts. So you can have git submodules inside your hugo site that specifically cater to generating these custom, single page html that you just want to add to your website.
So all I want is to have a menu item or sidebar whatever the existing theme supports, but instead of showing the default html, it should show my custom, hard-coded, already ready and prepared html file - which may as well be an index.html file in a folder with all the necessary contents ready and cooked - something like the _site folder that jekyll creates.
What do you mean by custom html?
I mean it doesn't take the formatting of the hugo theme. It has its own formatting, but because its just a single page in the whole website its not fruitful to have its own layout written in Hugo or maybe its just worth the effort to do that cause you already have it working using some other technology.
What have you done so far and what works?
I am actually coming from a Jekyll background where it's as simple as changing the layout frontmatter and making it nil or even something that doesn't exist at all and jekyll does a great job of showing custom HTML in an existing theme. Tried the same with Hugo but that didn't work.
What are you testing on?
hugo-coder and(or) hugo-academic
Any specific requests?
Ideally I would like to have submodules in my hugo site folder where those submodules generate custom html in known folders and then somehow make a corresponding markdown file in Hugo that is responsible for showing the custom html.
I want to avoid writing the whole html in the markdown itself. But if no other solution is possible then I guess I don't have a choice.
Do let me know if its possible and worthwhile to pursue this and any references that might help.
So I don't know if this is the perfect solution but it somehow works for the moment. I will not accept it as its not perfect and I am waiting for some of the more experienced folks to answer.
I got something working by doing the following -
I had a page built using Jekyll. Jekyll builds the site in a folder called _site.
I copied the _site folder into static folder of Hugo and renamed it correspondingly to CustomHTML OR you could use the flag -d <destination folder> or declare it in the _config.yml file : destination: <destination folder>
Since I am testing it on hugo-acdemic theme, for that I added the following to the config.toml file to show it in the menu -
[[menu.main]]
name = "CustomHTML"
url = "CustomHTML/index.html"
weight = 50
hugo serve And it worked.
Cool thing is that I didn't have to bother about CSS and anything else. Hugo rendered the index.html in _site properly.
EDIT
Looks like the Hugo folks also suggest doing the same way.
So I faced a problem while trying to add some SEO optimization for my simple static website served via Github Pages.
As the documentation says: https://help.github.com/articles/search-engine-optimization-for-github-pages/
I created the _config.yml file which includes next lines of code:
plugins:
- jekyll-seo-tag
and pushed this file along with my website files, so the structure looks like this
The problem is that after linking to my website I see the
output
And the head tag includes following content
I need help in understanding why the SEO plugin doesn't work. Thanks for all your replies and have a nice day!
If you want any file to be processed you must add a front matter to it.
Your index.html must be like :
---
# even an empty front matter is ok
---
<!DOCTYPE html>
...
David Jacquel's answer helped so much and I managed to resolve a problem. More about that:
I had to inject a valid front matter to resolve a problem e.g.
---
layout: main
title: Cheaterino
---
After that I still didn't manage to deal with the problem since my index.html was minified and so do the front matter.
After I disabled minification of the file everything worked!
head tag content after plugin worked
Thanks so much to David Jacquel!
I have just started trying to use jekyll for github pages.
I wished to use the theme leap-day.
Following the instructions, It just came up with some can not find post / can not find page errors, I followed the instruction ongithub to create _layouts/page.html and _layouts/post.html
Now I am finding it is complaining it can't find home layout.
Jekyll theme leap-day has just one layout: default.html while most of the times the first Jekyll version uses minima who has three: default, page and post.
To properly use leap-day make all your pages/posts and home page use layout: default.
I just started rails today and it's very interesting. However, I've come across a problem. Whatever goes into application.html.erb should be seen in other webpages; such as the links, navbar. The problem is what I've put into application.htlm.erb is not showing in the other pages. If I put 2 links into application it won't show on the other webpages, the only way I could see the links is because I manually inserted the code into the individual webpage. I don't know if it's something wrong with application.html.erb itself, but I have 2 files in the layouts folder: application.html, and application.html.erb.
I'm also watching a video that goes along with my project, which means that I pretty much copied whatever the teacher was saying.
I really want to move on, but this problem is putting me back. If anyone can help please respond!
There should only be application.html.erb in the layouts folder. The ERB extension is a rails filename extension that allows you to Embed Ruby code and PARTIALS.
application.html.erb is your master layout file, it renders partials and assembles the HTML structure in a modular way. It gets more apparent when your application grows!
Basically you are not supposed to edit application.html.erb directly unless you want to make a change to the existing HTML structure, which is basically
<html>
<head>
</head>
<body>
<%= yield %>
</body>
</html>
If I were you, I would read the Rails Docs about layouts. It explains how pages get rendered and shows you where to place your logic (in this case your links).
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">