{"id":16781475,"url":"https://github.com/ppintosilva/cool-course","last_synced_at":"2025-08-04T01:35:04.087Z","repository":{"id":95354534,"uuid":"149151543","full_name":"ppintosilva/cool-course","owner":"ppintosilva","description":"Repository template for developing and publishing a teaching course on the web","archived":false,"fork":false,"pushed_at":"2018-09-19T12:26:54.000Z","size":1655,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-16T21:12:27.938Z","etag":null,"topics":["asciidoc","course","course-materials","course-work","html5","reveal-js","reveal-md","template"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ppintosilva.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-17T16:01:59.000Z","updated_at":"2019-05-19T18:16:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"9a9f2997-fcb0-4291-a1f1-1b9198749073","html_url":"https://github.com/ppintosilva/cool-course","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ppintosilva/cool-course","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppintosilva%2Fcool-course","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppintosilva%2Fcool-course/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppintosilva%2Fcool-course/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppintosilva%2Fcool-course/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ppintosilva","download_url":"https://codeload.github.com/ppintosilva/cool-course/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ppintosilva%2Fcool-course/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268636977,"owners_count":24282221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","course","course-materials","course-work","html5","reveal-js","reveal-md","template"],"created_at":"2024-10-13T07:43:08.377Z","updated_at":"2025-08-04T01:35:04.017Z","avatar_url":"https://github.com/ppintosilva.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cool Course\n\nRepository template for developing teaching course material in simple markup text files and publishing it in html, via **gh-pages** or a simple http webserver.\n\nhttp://pedroswits.github.io/cool-course/\n\n---\n\n## Overview\n\nThe material of this course is composed of presentation slides and practical coursework.\n\n### Slides\n\n[Revealjs](https://github.com/hakimel/reveal.js/) is used to create presentation slides. These are written in [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) and converted to a static website via [reveal-md](https://github.com/webpro/reveal-md).\n\n### Practicals\n\nCoursework material can be easily written in asciidoc. Using [asciidoctor](https://asciidoctor.org/docs/user-manual/) we can convert the source asciidoc files into self-contained static html files which can be deployed on a webserver and nicely viewed on the browser.\n\n## Usage\n\n### Starting your course repository\n\nYou probably want to use this repository as a basis for your own course-material repository. The best solution, in my opinion, is to clone this repository, [remove all history, make commits and push to your own repository](https://stackoverflow.com/a/9683337):\n\n```shell\n# Step 1\ngit clone https://github.com/PedrosWits/course-template COURSENAME\ncd COURSENAME\n\n# Step 2\nrm -rf .git\n\n# Step 3\ngit init\ngit add .\ngit commit -m \"Initial commit\"\n\n# Step 4\ngit remote add origin \u003cgithub-uri\u003e\ngit push -u --force origin master\n```\n\n### Writing the content\n\n#### Generic Course info\n\nGeneric information about the course, e.g. overview and schedule, should be written in **asciidoc**. These should be placed under the `docs/` folder.\n\n#### Slides\n\nThe slides for your talks are **revealjs** and can be written in markdown. Place them under the `docs/slides` folder.\n\n#### Coursework\n\nThe coursework speaks **asciidoc**. These should be placed under the `practicals/docs` folder.\n\n### Installation \u0026 Requirements\n\nInstallation is as easy as:\n\n```\nmake install\n```\n\nThis installs **asciidoctor** and **compass** as ruby gems, and **reveal-md** locally via npm.\n\nFor these to work you need:\n\n- [ruby](https://www.ruby-lang.org/)\n- [gem](https://rubygems.org/)\n\nto install the **asciidoctor** and **compass** ruby gems, and:\n\n- [node](https://nodejs.org/)\n- [npm](//https://www.npmjs.com//)\n\nto install **reveal-md**.\n\n### Generating the html\n\nGenerating the html is as simple as:\n```\nmake html\n```\n\nMake reads the file structure in `docs` and creates the corresponding html file structure in the `build` folder.\n\n```\nbuild\n├── coursework\n│   └── sample.html\n├── images\n│   └── icons\n├── index.html\n├── overview.html\n├── schedule.html\n└── slides\n    └── example\n```\n\nCoursework documents, written in asciidoc, generate a single self-contained html file, but slides documents, written in markdown, generate an entire directory containing the necessary files revealjs presentation (`build/slides/example`). However, both result in static html content, directly deployable on a webserver.\n\n**NOTE:** Only the input files with the following patterns are inspected and converted to html by the makefile:\n\n- `docs/*.adoc`\n- `docs/slides/*.md`\n- `docs/coursework/*.adoc`\n\n### Asciidoctor extensions\n\nAsciidoctor extensions allow you to customise some of the nicest things about asciidoc. Here, I provide an example of how to write and use a custom admonition block, with a custom icon image. More information can be find in asciidoctor's [user manual](https://asciidoctor.org/docs/user-manual/#extensions) and examples in their [extensions lab](https://github.com/asciidoctor/asciidoctor-extensions-lab).\n\n\n## Deploy to **gh-pages**\n\n### Manually\n\nI suggest following the [approach](https://gist.github.com/cobyism/4730490).\n\nHowever, this comes at the cost of removing the **build** directory from the gitignore file, which doesn't seem to make it a very elegant solution. On the other hand, it simplifies things a lot. Everytime there's an update to the **build** folder, you commit it to master and push the changes to **gh-pages** using git subtree:\n\n```\ngit subtree push --prefix dist origin gh-pages\n```\n\n### Continuous Integration\n\nIf you want commits to master to automatically update **gh-pages** then continuous integration is the way to go.\n\nI tried using **travis-ci** and **circle-ci**. The latter felt easier to customise (since we're using Ruby and Nodejs in the same build), but I couldn't get it to work properly in the end as Chromium would break when running **reveal-md**.\n\n### Finally\n\nRemember to activate GitHub Pages on the settings panel of your repository.\n\nIf the steps above run successfully, the project's gh-pages should be available at:\n\nhttp://GIT_WHOAMI.github.io/GIT_PROJECT/\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppintosilva%2Fcool-course","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fppintosilva%2Fcool-course","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fppintosilva%2Fcool-course/lists"}