Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nicolas-van/easy-markdown-to-github-pages
Convert Markdown files in Github to a full website using Github Pages
https://github.com/nicolas-van/easy-markdown-to-github-pages
github-pages jekyll markdown
Last synced: 5 days ago
JSON representation
Convert Markdown files in Github to a full website using Github Pages
- Host: GitHub
- URL: https://github.com/nicolas-van/easy-markdown-to-github-pages
- Owner: nicolas-van
- License: mit
- Created: 2018-03-08T09:57:37.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-10-29T20:57:44.000Z (about 2 years ago)
- Last Synced: 2024-12-10T00:35:54.000Z (13 days ago)
- Topics: github-pages, jekyll, markdown
- Homepage: https://nicolas-van.github.io/easy-markdown-to-github-pages/
- Size: 440 KB
- Stars: 106
- Watchers: 3
- Forks: 156
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Easy Markdown to Github Pages
## Introduction
This little guide demonstrates how to turn any [Github](http://github.com) repository with a bunch of [Markdown](https://en.wikipedia.org/wiki/Markdown) files into a simple website using [Github Pages](https://pages.github.com/) and [Jekyll](https://jekyllrb.com/).
* You don't need to use the command line or anything other than your browser.
* It doesn't require any knowledge in Jekyll.
* It's completely compatible with any bunch of markdown files you already have in any existing repository without any modification to those files. That includes the basic `README.md` almost all repositories contain.
* The markdown files will remain just as readable and usable in Github than in your website.In fact this guide uses the same configuration and can be read both in Github and in Github Pages, at your preference:
* [Here is the link to the Github version](https://github.com/nicolas-van/easy-markdown-to-github-pages)
* [Here is the link to the Github Pages version](https://nicolas-van.github.io/easy-markdown-to-github-pages/)## Step by step instructions
### Determine the repository where you want to activate Github Pages
You can of course create a new repository if you want.
### Create the `_config.yml` file
That file should be created on the root of your repository. Here is some content to copy-paste in it:
```yaml
plugins:
- jekyll-relative-links
relative_links:
enabled: true
collections: true
include:
- CONTRIBUTING.md
- README.md
- LICENSE.md
- COPYING.md
- CODE_OF_CONDUCT.md
- CONTRIBUTING.md
- ISSUE_TEMPLATE.md
- PULL_REQUEST_TEMPLATE.md
```It's basically just a few tuning of Github Pages' default configuration to have a better handling of Markdown files.
### Activate Github Pages in your repository configuration
On the Github page of your project go into `Settings > Options > Github Pages`:
![](./printscreen1.png)
In the `Source` option, select `master branch` then `Save`:
![](./printscreen2.png)
You must also choose a theme:
![](./printscreen3.png)
That's it! Now you can just use the link provided by Github to access your website:
![](./printscreen4.png)
## Usage guide
* Any markdown file in your repository will display in your Github Pages website. You just have to use the same path to access it and replace the `.md` extension by `.html`.
* To make links between your Markdown files just use a relative path to the other Markdown file. The configuration you copy pasted in your `_config.yml` provides a plugin to convert those URLs. So your Markdown files will have correct links both in Github and Github Pages.
* The index page of your website can be a `index.md` file or a `README.md` file. If both exists the `index.md` file has priority.
* You should be able to use any [Github Flavored Markdown](https://guides.github.com/features/mastering-markdown/).## Known differences between Github and Github Pages
* No automatic links with Github Pages. The Github Markdown renderer can automatically detect a simple copy-pasted link and make it a clickable link. Github Pages doesn't propose a feature to reproduce that behavior, so you'll have to braces your links with the `[]()` syntax.
## Recipes
Since the purpose of this guide is to demonstrate how to publish multiple Markdown files as a website but I don't have much more to say I will propose to you some delicious recipes instead:
* [Escalivada](./recipes/Escalivada.md)
* [Gazpacho](./recipes/Gazpacho.md)
* [Pasta all'amatriciana](./recipes/Pasta_all_amatriciana.md)## Other Github Pages related projects
I'm a fan of Github Pages for the possibilities it offers to anyone to publish a website for free. I have multiple projects that could be of interest if that's your case too:
* [Bootstrap 4 Github Pages](https://nicolas-van.github.io/bootstrap-4-github-pages/)
* [Parcel Github Pages Boilerplate](https://github.com/nicolas-van/parcel-github-pages-boilerplate)## Contributing
See the [Contribution Guide](./CONTRIBUTING.md).
## License
See the [License File](./LICENSE.md).