I'm not sure it's even possible to solve this problem - but I'd ask anyways:
I'm working on a python project using mkdocs for the documentation.
The project structure (simplified) looks roughly like this:
./
|-- docs
|-- index.md
|-- page2.md
└-- [other documentation stuff]
|-- [the actual program stuff]
|-- README.md
└-- mkdocs.yml
I'm using the markdown_extensions markdown_include.include (declared in the mkdocs.yml),
and the index.md consists only of the line {!README.md!} to include the markdown file at this place.
This works nicely, displaying the README.md as the overview page of the docs.
The problem I ran into now is that in the README.md, I want to have a statement "For more detail, see XY", where XY should be a link to a heading in page2.md in the docs.
With mkdocs, I can simply write see [here](page2.md#heading2), and that works perfectly in the docs. But when I look at the README.md directly (e.g. on github), that gives me a 404.
When I put see [here](docs/page2.md/#heading2), it works from the README.md, but not in the docs created by mkdocs.
Is there any good way to work around this? Help would be much appreciated!
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
I bought a simple Jekyll template for a support site and have that up and running no issues.
I am trying to render my existing docs collection with separate layout. For background I am taking these docs and making a stripped down html file that has just the body content to use in a small modal pop-up window.
In my config file I have this:
defaults:
# _docs
-
scope:
path: ""
type: docs
values:
layout: doc
which renders my regular HTML files fine along with all my other template content in the target directory.
I am looking to also process this:
defaults:
# _docs
-
scope:
path: ""
type: docs
values:
layout: modal
The issue is that it seems in Jekyll can't do this out of the box. If add this to my config file it only uses the last one. If I try multiple config files they over write each other. I just want my full HTML docs using the doc layout in /docs and the HTML partial files rendered with the same docs collection using the modal layout in /modals as detailed in my previous post Multiple layouts for a single Jekyll collection?.
What I would like to do now is make a separate config file that builds ONLY the docs (using the modals layout) and NOT any of the other files (index, search, posts, 404 etc.) - just the docs collection with the alternate layout. I want the target folder to be the /modals sub directory of my main Jekyll.
This my hack so far - I won't even accept my own answer as it's not really a solution:
I have a second identical config file with this:
keep_files: ["docs"]
collections:
docs:
output: true
permalink: /modals/:name
I run this after the running the main config file. Keeps the normal docs build then adds the custom modal version.
I'm new to Jekyll and build a webpage using the TeXt Theme. I downloaded all files and created a local Jekyll website which runs successfully. The project folder contains the folders
_data
_includes
_layouts
_posts
_sass
_site
assets
docker
docs
screenshots
test
tools
The rest of the files in the folder are _config.yml, index.html, etc.
Now let's say I want to create a new page "Bio" that appears as an entry or name in the navigation bar at the top of the website like "about" or "archive".
I create a .md-file in the main project folder (i.e. where index.html lies) and specify in the front matter the layout - in the case of TeXt it is
layout: page
Also, in the _data folder I open the navigation.yml and append under "header" a new title called "Bio", i.e.
header:
title: Bio
url: /Bio.html
This is completely analogue to the about-page that is in the navigation bar and works properly.
But when I do it like this with Bio I get a 404 error and Jekyll is not able to find the site.
I searched all folders of the project and found that Jekyll does not create the necessary.html-file Bio.html on the basis of Bio.md. It just moves Bio.md into _site.
Hence, the url given in the navigation.yml cannot be found and I get the error. How do I get Jekyll to create the Bio.html?
If Bio.md is just copied, that means that Jekyll thinks it's a static file.
You're certainly missing a correct Front matter.
Your Bio.md should look like :
---
layout: page
title: Bio
---
## Content here
...
If problem persists, please add a repository url to help debug.
I figured out the answer myself. It is the notorious UTF-8 BOM issue with Jekyll. The file Bio.md was written in Notepad which uses BOM by default. Using ANSI instead solved the problem entirely without changing anything at the previous front matter.
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've been using Jekyll 2.0 directly from the command line for the last few days. I've put all my page files into a '/pages' folder so it looks like this:
/pages
- index.html
- about.html
- contact.html
In the front matter of each page I set the permalink like this:
permalink: /about/
So when Jekyll compiles the site, I'm able to navigate successfully to localhost:8888/about/ it's been working really well.
The Grunt/Yeoman problem:
I've picked up the generator-jekyllrb for Yeoman today because I want Grunt to manage everything (live reloading etc). I set it up, everything is working fine... but Jekyll is no longer generating the folders according to the permalink.
For example, my "about.html" page inside /pages, is not having an "/about" folder generated in the root like it did when using Jekyll directly. So I can only access the page through: localhost:8888/pages/about/. Which is strange.
Here's my Gruntfile.js generated from Yeoman
I don't know a whole great deal about this stuff. I'm very new to Grunt and the CL, but this has really stumped me. If anyone could offer any advice or point me in the right direction I'd really appreciate it.
I ended up adding the following to my _config.yml:
relative_permalinks: false
which fixed the problem. I think grunt-jekyllrb must be a version behind or something, because absolute permalinks are defaults now in the latest Jekyll.