This is a project page template for McGill-NLP projects.
You can follow one of the following ways to get started.
If you have not yet created a repo for your project, you can copy the template from the following link. Simply click on the "Use this template" button, or click here.
If you have already created a repo for your project, you can clone the template and copy the files to your project. Let's assume you are in the root of your project directory, e.g. my-project
.
cd .. # Go to parent directory
git clone https://github.com/McGill-NLP/project-page-template
cp -r project-page-template/docs my-project/
cp project-page-template/README.md my-project/docs/
cd my-project/
Once the template is copied to your project, you need to activate GitHub Pages for your project.
- Click on the "Settings" button in the top right corner of the page.
- Click on the "Pages" tab.
- In "Source", select branch to be "main" and folder to "/docs".
- Click on "Save"
- Go to the "Actions" tab (on the right of "Pull requests" tab) and wait for the action to finish.
- Visit your project page at mcgill-nlp.github.io/
You might be wondering why all the files for the webpage is in /docs
. Well the page is not really "docs" per se, it's because github-pages
only allows us to either use the root folder or /docs
. So we are forced to use the latter in order to clearly separate this page from the rest of the project. Maybe in the future GitHub will allow other names like /page
, but before then there's nothing we can do...
Well technically, you can push everything to a separate branch, but the original author of this repo is in the school of thought that branches are meant for alternate or historical versions of the
main
branch, or serve as a way to create pull requests. The original author will also vehemently defend this philosophy if one tries to argue otherwise :)
But what if you actually want to write some docs for your library? You can just edit docs/_pages/docs.md
, which is the real page for documentations.
You can already find links to different pages in the navigation bar. To add, remove, or modify links, you can edit docs/_data/navigation.yml
file. The title
corresponds to the text that appear on the navbar, and the url
corresponds to the relative URL of the page. It is not recommended to include an external URL, as that should be in /home
page.
The files are located in docs/_pages/
. For example, if you want to modify the /home
page, you would edit docs/_pages/home.md
.
All of the pages are markdown files with something called a front matter at the top, which uses the YAML syntax. Generally, all you need to worry about is the title and the permalink (the latter is the relative URL of the page). In the case of /home
, you also need to specify external links (header.actions
) and author names (excerpt
). However, a template is already provided for you, you only need to modify the content.
To add a page:
- Create a new file in
docs/_pages/
, with the desiredpermalink
to be your relative URL. So for example,/contact/
links tomcgill-nlp.github.io/my-project/contact
. - In
docs/_data/navigation.yml
, add a new entry with thetitle
andurl
from the previous step.
To remove a page:
- Delete the file in
docs/_pages/
. - In
docs/_data/navigation.yml
, remove the entry with the sameurl
as the deleted file.
Note that there's a tab that says docs
, and you can see that it links to other pages. So this is a standalone doc page inside your webpage. Note also that, due to Github pages' caveat, we were forced to put the webpage in /docs
, but the actual docs are in /docs/_docs
. Now that's cleared up, you can head to /docs/_docs/README.md
to read the instructions.
Do you feel writing documentation is too complicated or time-consuming, and you'd like something more straightforward? Check out the template for using MkDocs instead. However, the simplicity comes at the cost of more repositories and different frameworks to maintain.
For any advanced modification, it is recommended to look in the advanced section of the readme of the group website. Below are a extra tips included for convenience.
Please refer to setup instructions in the readme of the group website.
cd docs/
bundle exec jekyll serve
To remove dark mode, inside docs/_config.yml
file, remove dark_theme_css
. The dark mode should automatically turn off.
Inside docs/_config.yml
file, you can modify the footer.
If you want to modify the excerpt in the /home
page, you can do so in docs/_sass_/splash.scss
. Note that splash.scss
was added specifically for this template, not for the group website.
This is handled in docs/_includes/page__hero.html
. That file was added specifically for this template, not for the group website. You can modify that file to add, modify or remove icons.