I'd like to use Jekyll for my website, but I can't figure out how to set it up. All of the documentation I've seen shows how to use Jekyll to set up a blog. I just want to write Markdown and have Jekyll convert it to a website.
I understand that this question is a bit vague and the terminology may not be perfectly accurate. I'm new to creating a website and I don't want to learn HTML.
(Disclosure: My website will be for a project on GitHub.)
There's four types of document that you can find in a Jekyll site :
Static files like js, css or even html page. They don't have a front matter, are simply copied at generation time and can be found in the site.static_files hash,
posts they are located in _posts folder, have a front matter and can be found in the site.posts hash by liquid,
pages they can be anywhere in your folder structure, have a front matter and can be found in the site.pages hash by liquid,
collections that are more elaborated pieces of datas with a front matter and can be found in site.collections hash by liquid.
You can choose to use any of them. If you don't want to use posts, just remove or empty the _posts folder and just use pages.
If all you want to do is write markdown and have that generate a single page for a project, consider using the GH-pages automatic generator.
In step 3 you write the content for your page in Github-flavoured Markdown and then select a layout to publish it in.
Related
I have about 1000 regular static html pages in the GitHub repository (book). I regularly edit these pages using a special program. Each page contains only content; no header, footer or table of contents.
I want to use Jekyll to host them on Github Pages so that each page has a header, footer and a navigation block - a tree-like table of contents on the left side of browser. The table of contents is also a prepared static html file, common for the entire book.
The easiest way is to use frames, but this is not considered the best option.
I want the result to be something like https://rust-lang-nursery.github.io/rust-cookbook/
I have scanned github (search all repositories for _config.yml file) but have not found any similar use of Jekyll.
Can I do something like this using Jekyll?
This is an ideal use-case for a static site generator like Jekyll:
You might need to convert your content to Markdown or clean them up depending on the HTML
Each page has a common layout with the header, footer and navigation
You can make a separate page for table of contents by iterating over your pages inside a separate template
There's not really a concise answer here, short of learning more of Jekyll's feature set to become familiar with the concepts referenced above:
https://jekyllrb.com/docs/
https://cloudcannon.com/community/learn/jekyll-101/
Here's a template with a live demo that is made for hosting a book. You could use this as a starting point: https://github.com/CloudCannon/author-jekyll-template
I would like to create a gist in which I can present a main markdown document containing a set of links. These links will point to secondary markdowns which actually contain the code examples and technical explanations:
Here's what I have so far. I have included two markdown files:
Notes.md: contains a listing of existing secondary markdown documents
tree_traversal.md: an example of such a secondary markdown
As you can see I have tried to add a link in Notes.md to tree_traversal.md using the following syntax:
example of a [link](tree_traversal.md)
However there are two issues:
The Gist server attempts to display both Notes.md and tree_traversal.md. This is not what I want. I want to have Notes.md display first, then click on the link to navigate to tree_traversal.md
When I actually click on the link I created in Notes.md I get a 404 Page not found error.
Is it possible to have a multi-page gist like this? If so how? If not is gist only designed to have one markdown file?
Mousing over the tree_traversal.md header we see that it is a link to
https://gist.github.com/awa5114/4052ba8adb51779192a4a715a048f8ca#file-tree_traversal-md
Try simply linking to #file-tree_traversal-md in Notes.md. This should let you link between files, though they will both still be rendered in a single view.
Gists are designed for quick snippets, not documentation. Maybe you are looking for GitHub wikis? Wikis can be cloned via Git, managed locally, and pushed back, and they render pages one at a time.
Or possibly GitHub Pages, which can be used to host static websites?
I have a project on github that includes a number of markdown files (introduction, user guide, examples, reference).
I want to create a website using Github Pages based on these files that also includes a navigation element of some sorts, like a simple sidebar containing links to all the generated pages.
It seems that, out-of-the-box, pages generated with Github Pages are all stand-alone with no way to navigate between them.
Is there an easy way to achieve this, or is this use case too complicated for github pages? The documentation seems to be lacking on this point.
The Markdown to link to pages within the same folder
[__PageA__](PageA.md)
[__PageB__](PageB.md)
To link to pages in other folders just put in the relative link like this
[__PageC__](FolderC/PageC.md)
[__PageX__](../../PageX.md)
This works for files hosted on GitHub ... how you then use these to generate a standalone website you would need a tool that converts Markdown to HTML, something I have not looked into.
I'm planning to try using dokuwiki to manage my large collection of notes, and one of the major attractions is its flat file basis that'll allow me to edit via scripts etc. I had a question - suppose a page's material fits into multiple namespaces. If I were to create the file in one namespace and then create symlinks in the other namespace directories, would that work? Or would that screw up revisions etc?
Yes, you can do that. But yes, this will mess with your revisions a bit:
when DokuWiki saves a page, it copies the data of the old page to the attic
the name of the attic file is the same as the page that was edited, but with a timestamp appended
because new attic files are created you can't work with symlinks in the attic
Imagine you have the following setup:
data/pages/original.txt
data/pages/copy.txt -> original.txt
You now can edit the pages original and copy in your wiki and they will both always be the same. However old revisions of the pages will be split between the two, depending on which page you edited.
Instead of messing with file level consider
Include plugin to share content between pages.
Creation of some 'commons' namespace for such pages to be DRY.
Namespace templates (+ additional plugin).
Pulling content from page side instead of pushing it to pages. This might be good to start with. You can always include some php code or even write your own plugin.
Since the GitHub wiki does not support directories, I want to put my md files into GitHub pages. However when I open them I found they are not interpreted at all. GitHub just gives me the raw file. See http://greenlaw110.github.com/Rythm/en/index.md. Any idea?
The documentation isn't particularly clear on this, but given that the Markdown rendering is done by Jekyll, I believe you need what they call "YAML front matter" for it to compile the page. So try putting this at the top of your file:
---
title: Document Center
---
That should be enough to trigger Jekyll. (And then you can get fancy and start using layouts, etc.)
Another reason (found by experience) why you might get a raw index.md file, is if you happen to also have a similarly-named index.html file. This blocks GH Pages.
Deleting index.html produces (on the site) a new index.html with parsed markdown. The original index.md is then no longer accessible.