Gist Vs. Repository for Tutorial

Question

I'm publishing a tutorial that includes a lot of code interspersed with documentation. I'm considering two ways of hosting the code:

1. Separate git repository with code files and markdown files explaining the code
2. Github gist containing both of these

Are there advantages of hosting in a gist v/s a repository? When would one prefer one of these over the other?

Answer 1

If you use markdown files for your tutorial, now there is one important difference, even if you are only creating one file (and specially if it is a long one).

Since April 2021, .md files created in github repositories now include an automatic Table of Contents which greatly improves navegability. See this related SO answer for more info.

As far as I know, this automatic ToC does not exist in gist-created .md files, so I'd rather go for a repository in this case (OP mentioned "a lot of code interspersed with documentation").