Question: what software should I use to achieve a static site generator like described below?
I'm looking for a static blog generator, which... generates static blogs, of course :). However I need something more, like a nice set of themes to choose from, and, what is even more important, a specific way of managing assets.
When I write articles/posts/text, I create a new directory. Then inside I have a file like article.md, or article.textile. I also have files with code, and pictures, and charts etc. Everything is inside this one directory. Then I used to run a tool to convert it to html, and copy the html to a website for publishing. However there was always a problem with images. I had to copy the images somewhere e.g. to Wordpress and then change the image urls in the html. This is not the best way to do it.
I'd like to have a static blog generator, which would let me keep my normal structure: one directory per post, and keep all the images from the directory in generated structure, so I can have relative paths to the images.
I really don't like the idea to keep all articles in one global directory, and all images in another global one.
I've checked jekyll, and pelican so far, and read about couple others, but I haven't found any solution to that problem. I know that, as usually, you will have many nice ideas to check.
And of course I know that most probably this post will be "closed and not constructive", or with any other funny explanation, but maybe someone will manage to post any solution before that.
Hugo can do this. cd to empty folder of your choice, then
create the scaffolding:
hugo new site .
After that you can put your content in content, example:
content
post
alpha
index.md
1.jpg
2.jpg
bravo
index.md
1.jpg
2.jpg
Build site:
hugo
Result is generated in public folder:
public
post
alpha
index.html
1.jpg
2.jpg
bravo
index.html
1.jpg
2.jpg
Jekyll does not explicitly enforce a rule about where to put your assets like images with the exception that Jekyll will not copy files directly in a folder beginning with an underscore. Although the general practice would be to put all images in the \assets\ directory, you can put it anywhere else other than the _posts\ directory, which is what you wanted.
This is the default behavior, but there are ways to get around this:
Have your posts live outside the _posts directory
Put all your posts outside the default _posts folder along with the images (this will copy all the files without any YAML frontmatter, and preprocess all the files with the YAML frontmatter). However, any other function you can do with posts automatically in Jekyll won't work anymore. This may or may not be an issue.
Plugins
Here's a plugin (link to SO question) written specifically for making Jekyll copy files in the post directory. If you do use this you can definitely just write the following Markdown and it'll link relative to the post as it should. :
Jekyll asset path plugin is another robust plugin that does something similar, but does not keep your images in one directory, it does however link images relative to your post title though.
Jekyll asset pipeline is another another plugin that handles CSS and JS, which might be something you want to have in conjunction with plugin 1.
Do note however that the use of third party plugins is not supported with GitHub Pages site generation, meaning you will have to generate them in another branch or locally, and then pushing the static HTML files to master. This might be an issue for you if you're planning to host with GitHub Pages, else on your own server instance you're good to go.
I also want my posts to be "self contained", text content and image assets being in one single folder. I'm using Jekyll.
I have made this possible with a Pull Request on the great jekyll-picture plugin.
I can then use the simple {% picture my-image.png %} syntax to show the image in my post that is in the same folder.
Here is an example: https://github.com/nhoizey/nicolas-hoizey.com/tree/master/_posts/2015/06/19-mon-jeu-esviji-integre-a-framagames
One year after my previous answer, I have now developed a Jekyll plugin that helps keep posts assets alongside the Markdown file, it might fill your needs: https://nhoizey.github.io/jekyll_post_files/
Related
Here is my repository on my Hugo blog:
I'd like to insert an image to a post with the following text:
However, it does not come out and it gives an error of 404 - Page not found.
What am I making wrong here?
You have a typo in the image link. You have an images directory, but reference "content/post/image/..." without the "s". That won't fix it for you though.
There are a few ways to link images.
Option 1. Put all of your images in the static/ directory. Then reference the image file with a leading slash, e.g.:
Option 2. Use sub-directories to hold the markdown file and any related resources.
create a directory post/creating-a-new-theme
move your existing markdown file into that directory, and rename it to index.md
create a subdirectory post/creating-a-new-theme/images and move your images in there
reference the image as 
More info on option 2: https://github.com/gohugoio/hugo/issues/1240#issuecomment-753077529
More options
There are more sophisticated ways to reference images using the frontmatter, as well: https://gohugo.io/content-management/page-resources/
TL;DR
Put your images in the static directory, just like below, use it in markdown like  or  if you don't want to build a post folder
If you search the hugo documentation, you can find Image Processing | Hugo
But! That's no a markdown way to insert an image. If you don't miss the Getting Stated, you will find the static Directory, which says can store images, that's it!
[static](https://gohugo.io/content-management/static-files/)
Stores all the static content: **images**, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the static folder is for verifying site ownership on Google Search Console, where you want Hugo to copy over a complete HTML file without modifying its content.
How to use it
Put your images in the static directory, just like below, use it in markdown like  or  if you don't want to build a post folder
static
└── images
├── my_post_folder
│ ├── my_image.png
└── my_image2.jpg
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.
I have multiple language versions of my website from the root folder as
en-ca/*
fr-ca/*
en-us/*
etc.
I have created a _resources folder that contains css common to all sites.
I would like to copy the content of the _resources folder into en-ca/*, fr-ca/*, en-us/*, etc. at build time.
Hmmmm.... Are you sure you want to do that? That doesn't seem like a good idea.
If the CSS is identical across the different languages, why would you make the end-users download the same file again when switching to a different language, if they already have the same file cached in their browser?
It would be better to have the common CSS in a single place, and have your HTML templates reference that instead, and leverage the browser cache, etc.
Anyway, to answer your question, if you want to use pure Jekyll (without a plugin), you can create empty common.css files inside each language folder, and use the tag include_relative to copy the contents of the common.css to it.
Jekyll Includes / include_relative
https://jekyllrb.com/docs/includes/#including-files-relative-to-another-file
Alternatively, you can write a plugin that copies the file to the folders you want. In the answer below there's a small example of a plugin that renames files... You can adapt it to copy files instead:
https://stackoverflow.com/a/48600246/211672
I am creating a blog on Jekyll for the first time and I am at the point where I'm trying to deploy what I have so far to github pages. When I serve the site and view it locally, it looks fine - so I thought that all I had to do was push all of the files to a gh-pages branch. Now that I have done this, all that is showing is the HTML.
To troubleshoot, I downloaded just the template files and pushed those to a Github page to see if the issue had to do with how I was editing the CSS, but when I did that I got the same results.
I came across an article that was specifically about how to use github pages to store a jekyll site, and it said to remove the slash before the css folder in the linked stylesheets on the HTML if your page isn't styled correctly. After reading that I thought that the slash was for sure the issue, but after removing the slash... I got the same result.
I have been trying for hours and I feel like its probably something very simple(such as the slash).
Here is the repo:
https://github.com/pacalabre/blog-site/tree/gh-pages
Here is the output:
http://pacalabre.github.io/blog-site/
Thank you in advance for any answers!
You need to add/edit:
baseurl: /blog-site
to the config file. Note there is no trailing slash. 'blog-site' is the name of your project, the project name becomes a sub directory that serves your site. Without the baseurl setting, your relative urls are trying to fetch things from http://pacalabre.github.io/ when they are really at http://pacalabre.github.io/blog-site/.
GH is serving your site as a subfolder to the domain and your references are not taking that into account.
Once you add the baseurl setting, you then need to add {{site.baseurl}} in front of your assets like images, css and js.
Also, once you do the baseurl setting, when you serve locally it will not be quite correct, you will need to add the /blog-site to the end of the localhost url for it to work properly.
You also should try using the dev tools inspector in Chrome to help you troubleshoot, it will clearly tell you right now that it cannot load all your js files or images, and it will show where it is trying to load them from.
Look, there's something wrong with your site/repo.
I didn't find your _config.yml at the site root ( gh-pages branch). It should be there.
There's a binary file there (probably Mac's file if I'm not mistaken). It shouldn't be there.
There are both Jekyll's folders (_posts, _drafts, _layouts, etc) and _site folder there. You need to choose. Or you upload the _site content (not the folder itself) or you upload the Jekyll project. Usually you upload just Jekyll folders and GH build the site for you, unless you use some plugins which are not allowed by GitHub. In this case, you upload just the _site content, which is the compiled site (html, CSS, js only).
On the previous answer, you were instructed to add a baseurl to your site configuration. It's the best approach, but if your template uses just url and doesn't even mention baseurl, the best way is adding the project name to the end of the url, not searching for every link to call {{ site.baseurl }} via liquid. So, instead of giving yourself all this trouble, better do like that in your _config.yml:
url: http://username.github.io/projectname
If you indeed go for setting up the baseurl, you can view your site locally via localhost:4000 by adding this flag when serving Jekyll: --baseurl "". So, jekyll serve --watch --baseurl "". This means like "Jekyll, ignore the baseurl set in the config". Got it?
Serving Jekyll with bundler is the right way to do that, specially when deploying to GH Pages. But this is another story, I can add a comment later if you're interested.
Suggestions. Read a little more about how Jekyll works. Also look for .gitignore so you won't upload to GH anything unnecessary (like that binary file).
After that, if your site doesn't build or display correctly, let me know and I'll help you out if you want.
Hope to have helped!
I was wondering how other people are organising their assets for individual posts when using Jekyll. For example, if a post has an image, do you just dump it in a shared images folder? I don't really like the idea of doing this - it means that an image is completely separated from a post, when I think they should be paired.
I wrote a plugin to let me organise assets in subdirectories easily:
https://github.com/samrayner/jekyll-asset-path-plugin
{% asset_path my-image.png %}
in post 2013-01-01-post-title would output:
/assets/posts/post-title/my-image.png
in page my-first-page would output:
/assets/my-first-page/my-image.png
I prefer to think of images as stand alone assets that are included in zero or more pages. Most of the time, my images show up in a single page. There are times when I want to have them in multiple pages and in other cases I don't link an image at all. If your workflow is to put each image in a directory with a post, finding them starts to require a significant amount of searching and you have to come up with something different for images that don't belong to a specific post.
The approach I use is on the opposite side of the spectrum. I have a single image directory (served from "/images") and 100% of my images are housed there. Benefits of this are:
When I'm adding an image to a post it's easy to know what path to use. It's always:
/images/{image-name}
For example: http://alanwsmith.com/i/aws-20111017--0906-02. This makes it possible to write a plug-in so all you have to enter is the image name and the rest of the known path is filled out automatically.
With an application like Photo Mechanic, it's incredibly easy to browse the single directory locally and see every image. If I want to include an image on another page, this drastically reduces the time to find it.
There isn't a separate location/process if I want to send an image to someone without actually including it in a page (i.e. send them a direct link to the image file). I just throw the image in the standard directory and send the direct link.
If you want to get a little more advanced, keeping all your images in a single directory makes some nice tweaks possible as well. For example, even though the URLs for my images start with "/images", the images are actually stored in a directory outside of the ones jekyll uses. In my case, the top of my source tree looks like this:
./html
./source-files
./image-files
All of my images are stored in the "./image-files" directory. In my apache config, I've setup an alias so that the URL "/images" points to the "./image-files" directory. For example:
Alias /images /webroot/image-files
When I run jekyll, it process everything in "./source-files" and drops it in "./html". Because all of the images are outside those two directories, jekyll never sees/touches them. As your image library grows this will help speed things up and will prevent a tremendous amount of unnecessary file copying.
Another tweak I like in Apache is turning on:
Options +MultiViews
This lets you call your images without having to use the file extension (e.g. no '.jpg', '.png', etc...). You can see that in the example link I provided above. It doesn't really matter for performance. I just like the way it looks and it saves me from having to type the extension every time I'm calling an image.
MultiViews also makes it possible to replace an image of one format with another without having to recode anything else. For example, if you remove "some-image.gif" and replace it with "some-image.png", you wouldn't have to touch any HTML. It would still be served form "/images/some-image". Needing to make changes like that is probably exceedingly rare. I just think it's an interesting thing to be able to do.
Finally, you can make a single decision about allowing or disallowing your image directory to be browsed. Personally, I only want my images to show up where I place them. So, I've set the .htaccess file in my images directory to:
Options -Indexes
If you are going to be working on a site with many thousands or tens of thousands of pages and images, this might not scale. For a normal sized, personal site, I find that this approach makes maintaining images easier.
I have now managed to develop a Jekyll plugin that helps keep posts assets alongside the Markdown file:
https://nhoizey.github.io/jekyll-postfiles/
Just like you, I really hate having all images in one single shared folder.
Most, if not all, of my images are useful in one single post, and keeping them alongside the Markdown file is really better for posts management:
I can drop a new post as one single sub-folder of /_posts/ in one step, without having to put the Markdown at one place and the image(s) at another
When I want to edit the image(s) of an existing post, I don't have to find the right image in a huge /assets/ folder, it is located just near the Markdown file
In my Markdown, I can use the image file name directly, without any path
If I want to use any Markdown editor with live preview, it works, no need for a specific assets folder configuration
I tried to have this for my blog (example post here).
For responsive images, I used the Jekyll Picture Tag plugin, but I had to fork it, because the Pull Request to deal with such paths was not accepted.
Now that Jekyll 3 is there, I wish it could let us use images both in a post folder AND in the /assets/ one, looking for an image marked with  in both, in that order.
For JavaScript and CSS, you may want to consider an asset pipeline. You can get a good performance improvement through bundling and compression. I also use CoffeeScript and Sass, so I needed a preprocessor to convert my assets. I use Jekyll Asset Pipeline to manage this whole process automatically when I run the jekyll command.
For images/video, I recommend you develop a convention for naming folders in your project. I generally have an "assets" folder then subfolders with the date of each post that holds the images related to those posts. If you have multiple posts per day, you might consider including the name of the post.
This answer:
Does not use plugins (works with GitHub Pages)
Allows you to keep images directly next to their relevant posts
Allows you to edit using Typora locally and see the images WYSIWYG
Just name your folders like _posts/2020-10-10-My-Title/ and include files like index.md and hero.svg or other images.
Then set your permalink: key in _config.yaml to :path.
Caveats:
Your folder names must be sluggified
Your images must all be SVG