The pitch for git pitch itself appears directed at developers, who apparently have the time and patience to write markdown code for slideshows, but don't have the patience to output html/js via something like reveal-md. The drawback is the inherent advertising of gitpitch. With reveal-md your slideshow can be uploaded as a static page(s) to your own domain, or even directly to GitHub pages.
Hi @rorosaurus please see my reply on this thread where I explain that any GitPitch presentation can be downloaded as a fully self-contained bundle (HTML/CSS/JS) with just one click. And that gives you exactly what you need to deploy your presentation wherever you like.
Hi @MaxLeiter I tried to include BitBucket in the title text but was limited to 80 characters so it simply did not fit. Apologies for the omission here but it was beyond my control.
Hi @xkr fair point. But to be clear, the hello-world example was written specifically to be embedded in the gitpitch.com website and it was designed to auto-play every slide so it could be watched almost like a short movie.
Typical presentations are something that the presenter manually steps through slide by slide as they speak. So needs none of fragment timing snippets you came across.
Almost any other GitPitch presentation out there is a better example of what's typically involved, for example, see this presentation from AnyCable:
But it still has all the <span>s for changing the color. That's not specific to gitpitch, but that takes away a lot from markdown I think. Once you start doing that, you can just write HTML to begin with..
The whole point of markdown is that it covers a very small subset of HTML in a human-readable way, and for any formatting beyond that subset you use regular HTML. Adding <span> tags to customize things is very much the intended way to write markdown.
Right, but maybe markdown isn't the right markup language for presentations.
This may be the correct way to add color in markdown, but it feels unnatural for the tool. I'm glad xkr brought this up it; it feels like hidden complexity.
Am I the only one that hates markdown? HTML just seems so much more intuitive to me. I can never remember how to make text bold or italic in Markdown. Is it 3 quotes? 2 quotes? Single quotes? Double quotes? Asterisks? Wait, is astersks for bold or asterisks italic? Try all the combinations and see what happens?
Compare that to <b> -- b for bold! <i> -- i for italic! Super intuitive!
And what about headings? Is it stars? pound signs? random rows of dashes? or is it equals signs? Does more pound signs make it bigger or smaller? What happens if the number of dashes or equals signs is different from the number of characters above it -- will my PC blow up? What if one of the characters is a Chinese character -- does it still count as 1 equals sign? Or 2? Or 3? Is it based on the number of bytes after UTF-8 encoding or the number of multibyte characters? Should I just screw it and use bold text as a heading instead of googling for markdown cheat sheets?
Compare that to <h1>, <h2>, ... same syntax as the bold and italic tags so you don't have to memorize a new syntax to do headings once you've learned how to do bold and italics. Isn't that revolutionary?
As a bonus, cleanly-written semantically-meaningful HTML you write can be styled to perfection with CSS in any old web browser without any clunky interpreters or middleware. You don't even have to install anything. Isn't that even more amazing?
Am I the only one that actually wrote a script to convert HTML to Markdown just so I can create those silly README.md files without having to remember some awfully inconsistent syntax?
It helps a lot if you have syntax highlighting for markdown in your editor.
I've written my share of bare HTML... I did it that for 10+ years somewhat infrequently. I started a blog and used markdown and now I'm happy. HTML would have been worse for writing frequently IMO. It's annoying to type and annoying to read.
One thing that is annoying is that hyperlinks tend to take up a really long line, more than 80 characters. You can't have a space after <a href=""> or before </a>, because that affects the appearance.
In its original form it was simply an aid to get static html from human readable text (<- that there is the basis for md).
For better or worse, it's been forked a few times, adding new abilities or even in efforts to make it stricter. The main idea of readability still applies. I could hand over a markdown formatted txt file to someone and they'd probably read it just fine, whether they could code or not. Html in plain-text form, though? Not sure that would work.
It has quirks, but the whole I really like it. I've used it for writing guides, taking notes... Maybe even for web content at some point.
If you limited yourself to a small set of HTML though and kept the structure simple, then it probably wouldn't be much less readable than a Markdown document.
<ul>
<li>item1</li>
<li>item2</li>
</ul>
<p>some paragraph with an <i>italic</i> word</p>
No need for body and html element, you can inject that afterwards.
I think the most important aspect of markdown is not the syntax but the standardisation of styles. No needing to worry about how to make it look nice it's not only time saving but very helpful when reading hundreds of other people manuals.
Really? The above HTML will look very readable if you just fire it up in a web browser. And if we all agreed on the location of an optional CSS file (e.g. ~/.default.css) anyone would be able to customize how all their documentation looks. It would be totally optional and just make semantically-good HTML go from readable to super-pretty per-user custom themes. Totally optional -- if you don't have it, you'll still have something extremely readable, well more readable than Markdown.
<html>
<head>
<link rel="stylesheet" href="~/.default.css">
</head>
... your documentation goes here ...
</html>
The best part? If you don't think <i>this</i> is readable, just double-click and open the thing in a plain-old web browser and it'll be more readable than Markdown.
when it comes to typing, and especially _editing,_ all that markup cruft becomes a distraction (at best), and usually much more like an irritating obstacle. and you glossed over the ’ which needs to sit in the middle of every contraction. like this:
“if you don’t have it, you’ll still have something...”
I am completely with you. I know what you mean. I have the very same problems.
From the history of Markdown, why it was invented? It is dead simple. John Gruber said: "I am en editor and HTML is to clunky for me, so I will reinvent the wheel and make it easier." It is basically the very same reason why we have HTML these days, because Tim said "SGML is to clunky for me, so I will reinvent the wheel and make it easier."
You need to remember, that John Gruber is a journalist/editor he writes articles for magazines (and now for the web). Presumably, he learned as a journalist to write simple plain texts with only a few marks to indicate headlines, comments, and alike. Then the layouter would do the job and layout the text for the magazine. It is even so today how most journalists work.
Also, I have been in the industry now for some time and I see that pattern over and over again. There is some kind of standard that evolved over time, because of feature requests in-cooperated into the standard. Then there comes some guy/girl with a very simple use case and thinks "This standard is way to complicated for my simple use case. I can do that better." Then this new way gets some attention and other people are speaking out loud "Yeah, we have the same trouble for some time. Lets make that new way standard and improve from that on, now." This new way will now become a standard. Lots of people having new feature request, because this old standard can do this cool feature the new standard can't, so lets in-cooperate that into the new standard. And so on, and so on. And the wheel will start over again with a new person.
BTW, you can apply the same pattern to programming languages. Remember why and how PHP started? Because Perl was a go to at the time, but it was to complicated for some people. Then came Ruby on Rails.
I'm not particularly a markdown enthusiast, but most of these gripes make no sense. Remembering whether more pound signs make a header bigger is no different than remembering whether <h1> is bigger than <h3>, and double-byte characters don't affect markdown any differently than they do HTML, etc. And for the "will my PC blow up if I use the wrong number of characters?", you're referring to a rule that accepts any number of characters.
All that's going on here is that you're used to one syntax, and not to the other. If one is used to both, markdown is quite nice.
Also:
> Am I the only one that actually wrote a script to convert HTML to Markdown just so I can create those silly README.md files without having to remember some awfully inconsistent syntax?
HTML is valid markdown - you can just use <b> and <h3> and so on, there's no need to convert them to markdown equivalents.
GitPitch was indeed launched with developers in mind. Devs often need to present and promote their work. Having worked as a software consultant for over 20 years I can attest to this. And with the rising popularity of tech meetups and conferences now more than ever making it easy to clearly present concepts, designs, etc. right alongside the actual code in your repo is a big win.
GitPitch is also seeing wide adoption across academia, particularly as a tool for delivering course materials, again right alongside the code.
As a final note, you mentioned a perceived drawback. GitPitch presentations are indeed automatically made available online just as soon as you git-commit and push to GitHub, GitLab or Bitbucket. But if you really want to host the presentation on your own domain or under your GitHub pages a fully self-contained bundle for your presentation is available for download with one click. You can then take the contents of that bundle (HTML/CSS/JS) and deploy it on your own Web server. No problem.
> GitPitch is also seeing wide adoption across academia, particularly as a tool for delivering course materials, again right alongside the code.
Okay, you peaked my interest. This is the slide (built via PowerPoint) that I use to explain a nested loop structure to CS1 students [1]. Explain to me, as an academic mind you, how I can recreate this without learning CSS animations / JS magic?
If I have to, that's fine, but all I'm asking is to make a circular motion animation. I'm demonstrating I can do that in 6 steps with PP; if technical knowledge is necessary, then it's a bit of a lie to say it can be widely adopted to academia.
Hi @tsumnia you can't use GitPitch to create animated graphics. There are lots of other tools for that. However you can use animated gifs within a GitPitch presentation, read about background images on the Image Slides page in the Wiki:
Or if you have a series of images that combined present some kind of animation or workflow you can use those images as an animation sequence as described by Image Animation in the Wiki:
Do keep in mind, GitPitch is not trying to offer everything PowerPoint is capable of. Far from it. But it is trying to offer just enough, in a lot of use cases. But perhaps not yours.
Not quite sure what you meant with "inner loop consumes an array of size size greater than that of the outer loop" but I'd like to say no.
In the graphic, we create two separate variables. The outer loop is only controlled through the X variable, meaning only when X is greater than or equal to 3 does it cease. If X started at a higher than 3 number, it doesn't run at all, but that's not the point of the example. The confusing part comes with the Y.
Y is the controller of the inner loop, and only gets incremented when the Y loop iterates. Once the inner loop completes, it still has 2 more instructions to execute (that belong to the outer loop), so it does them. That last line resets the Y variable, so that it can run the inner loop the next time.
It's actually a good question I ask as a follow-up. Suppose I delete the "y = 0;" line, how does that change how the loop behaves?
At no point does my X variable manipulate my Y variable directly (through loops yes, but not like y = x * 2). Like if I went through an old fashion phone book or dictionary, there are 26 letters (outer loop), but each letter has a varying number of words (inner loop). Then it'd read something like
while (x < 26)
{
while (y < NUMBER_OF_WORDS_STARTING_WITH_X)
{
y = y + 1;
}
x = x + 1;
y = 0; // otherwise, Y never resets
}
Hi @orschiro you can include GitHub GIST within any GitPitch presentation, see the GIST Slides section in the GitPitch Wiki: https://github.com/gitpitch/gitpitch/wiki
Please, please, don't mess with my page history. When I hit back in my browser, I don't want to go back a slide, I want to go back to the previous page.
Hi @andrewguenther individual slides appear in the history by default as it allows direct linking inside a slideshow. See Slide Direct Links in the Wiki:
It's related to Git because of GitHub and the fact that it does not work without GitHub. They should've called it GitHubPitchesPowerPoint.
Git is a magic word and GitHub knows it. Spell 'git' to summon professionals of all kinds. But by releasing GitPeach, GitHub wants to show that its average 'dev' user needs help with making presentations. Is that really a problem? Presentations? Thanks, I don't need GitHub for presentations.
Is this a joke, AI gone wrong, or do you really not understand what's being discussed here?
> it does not work without GitHub
Firstly - it currently works with GitHub, GitLab and BitBucket.
Secondly - it reads one markdown file from the repo. It could work from any url if they wanted it to.
> But by releasing GitPeach, GitHub wants to show
Let's assume thats some kind of weird autocorrect, and you meant GitPitch. Either way, GitHub isn't releasing anything here. It's a third party, who use GitHub to host the source code for the tool.
I highly recommend pandoc for this use case. Pandoc is amazing. I recommend it for all your markup. To write tech docs, books, presentations, blog posts, etc.
It lets you use Markdown to generate Html, Docx, Pdf, every other markup, and off course Presentations just like gitpitch.
Interesting, did not realize that was possible! Had to dig into pandoc a bit to find much information about presentations however as I have never actually read the manual to use it. Reference I found was page 60 of the pdf manual: https://pandoc.org/MANUAL.pdf
This reminds me of the present tool [1] that the Go project created, which I like and use for my slides these days. Main reason, which it shares with GitPitch, is the simplicity. It works for my basic needs, and I don't want anything more heavyweight.
For an example, see .slide source [2], and the presentation result [3].
This is very cool. One thing that I wish the docs made clearer was that this is a wrapper around `reveal.js`, so if you're familiar with reveal, then learning this tool is just a little more effort.
Hi @autarch, thanks for the helpful feedback. I'll make some changes to the docs to make this clearer so existing users of reveal.js will immediately feel right at home. It's probably also worth noting that you don't need any knowledge of reveal.js to use GitPitch, just write some Markdown and then git-commit.
Hi @alihcevik, GitPitch does not support private repos. However, if you want to keep your project code private but share the knowledge about your project using GitPitch then you can of course create a public repo just for your PITCHME.md presentation markdown.
Would you please not @reply people? HN has threaded comments; the usernames are right there. Repeating them is redundant and has the same cloying effect that it would on regular conversation.
Hi @izacus it certainly does. The offline feature was designed for this very reason. With one click you get a fully self-contained bundle that downloads onto your computer. Just open it and follow the simple instructions given here in the Wiki:
FYI: I've put together an alternative free (open source) presentation (slide show) static html generator from markdown called Slide Show (S9) - https://github.com/slideshow-templates Includes themes for reveal.js, deck.js, bespoke.js, s5, s6, and more. See PS: Since last year all theme packs / templates are GitHub Pages/Jekyll-compatible. See a ready-to-fork multi-talk site sample here - https://github.com/henrythemes/jekyll-talks-theme
PPS: I've used it for over 30+ talks in markdown, see some "real world" samples on GitHub - https://github.com/geraldb/talks
Great question. There is absolutely nothing wrong with reveal.js. In fact I like it so much I chose it as the underlying presentation rendering engine for GitPitch.
When you view a GitPitch presentation it is rendered by the reveal.js library. GitPitch simply provides a new way of delivering presentations that are powered by reveal.js that works seamlessly directly within GitHub, GitLab, or Bitbucket.
If you prefer to use the reveal.js library directly, or use their hosted service slides.com or any other of the great tools mentioned in this thread, then go right ahead. There is something for everyone. GitPitch offers it's own unique approach. And for some, that makes the most sense.
Personally, I'm very fond of it, due to it's
preview/note-showing feature which you will enjoy, after pressing C (clone) and P (presenter-mode) in the cloned window.
As with many alternatives, it doesn't pollute your slides with any unwanted ads or external dependencies.
88 comments
[ 3.1 ms ] story [ 145 ms ] threadThe pitch for git pitch itself appears directed at developers, who apparently have the time and patience to write markdown code for slideshows, but don't have the patience to output html/js via something like reveal-md. The drawback is the inherent advertising of gitpitch. With reveal-md your slideshow can be uploaded as a static page(s) to your own domain, or even directly to GitHub pages.
I write all of my course slides in markdown and they get published on commit with no external services.
Typical presentations are something that the presenter manually steps through slide by slide as they speak. So needs none of fragment timing snippets you came across.
Almost any other GitPitch presentation out there is a better example of what's typically involved, for example, see this presentation from AnyCable:
https://gitpitch.com/anycable/anycable
This may be the correct way to add color in markdown, but it feels unnatural for the tool. I'm glad xkr brought this up it; it feels like hidden complexity.
Compare that to <b> -- b for bold! <i> -- i for italic! Super intuitive!
And what about headings? Is it stars? pound signs? random rows of dashes? or is it equals signs? Does more pound signs make it bigger or smaller? What happens if the number of dashes or equals signs is different from the number of characters above it -- will my PC blow up? What if one of the characters is a Chinese character -- does it still count as 1 equals sign? Or 2? Or 3? Is it based on the number of bytes after UTF-8 encoding or the number of multibyte characters? Should I just screw it and use bold text as a heading instead of googling for markdown cheat sheets?
Compare that to <h1>, <h2>, ... same syntax as the bold and italic tags so you don't have to memorize a new syntax to do headings once you've learned how to do bold and italics. Isn't that revolutionary?
As a bonus, cleanly-written semantically-meaningful HTML you write can be styled to perfection with CSS in any old web browser without any clunky interpreters or middleware. You don't even have to install anything. Isn't that even more amazing?
Am I the only one that actually wrote a script to convert HTML to Markdown just so I can create those silly README.md files without having to remember some awfully inconsistent syntax?
I've written my share of bare HTML... I did it that for 10+ years somewhat infrequently. I started a blog and used markdown and now I'm happy. HTML would have been worse for writing frequently IMO. It's annoying to type and annoying to read.
One thing that is annoying is that hyperlinks tend to take up a really long line, more than 80 characters. You can't have a space after <a href=""> or before </a>, because that affects the appearance.
In its original form it was simply an aid to get static html from human readable text (<- that there is the basis for md).
For better or worse, it's been forked a few times, adding new abilities or even in efforts to make it stricter. The main idea of readability still applies. I could hand over a markdown formatted txt file to someone and they'd probably read it just fine, whether they could code or not. Html in plain-text form, though? Not sure that would work.
It has quirks, but the whole I really like it. I've used it for writing guides, taking notes... Maybe even for web content at some point.
<title>title</title>
No need for body and html element, you can inject that afterwards.I think the most important aspect of markdown is not the syntax but the standardisation of styles. No needing to worry about how to make it look nice it's not only time saving but very helpful when reading hundreds of other people manuals.
but you're just talking about _reading_...
when it comes to typing, and especially _editing,_ all that markup cruft becomes a distraction (at best), and usually much more like an irritating obstacle. and you glossed over the ’ which needs to sit in the middle of every contraction. like this:
ick. no thank you.is perfectly fine in HTML. If you for whatever reason believe left and right quotes should make a difference,
“if you don’t have it, you’ll still have something ...”
will be fine in HTML as well. You don't need awful escape sequences for these. Browsers will render them just fine.
and that's just from an "easy on the eyes" standpoint.
when i also think about actually typing all those unnecessary angle-brackets, i break out in hives. it's not "difficult". but it's terribly tedious.
but you should stick with what you like... :+)
From the history of Markdown, why it was invented? It is dead simple. John Gruber said: "I am en editor and HTML is to clunky for me, so I will reinvent the wheel and make it easier." It is basically the very same reason why we have HTML these days, because Tim said "SGML is to clunky for me, so I will reinvent the wheel and make it easier."
You need to remember, that John Gruber is a journalist/editor he writes articles for magazines (and now for the web). Presumably, he learned as a journalist to write simple plain texts with only a few marks to indicate headlines, comments, and alike. Then the layouter would do the job and layout the text for the magazine. It is even so today how most journalists work.
Also, I have been in the industry now for some time and I see that pattern over and over again. There is some kind of standard that evolved over time, because of feature requests in-cooperated into the standard. Then there comes some guy/girl with a very simple use case and thinks "This standard is way to complicated for my simple use case. I can do that better." Then this new way gets some attention and other people are speaking out loud "Yeah, we have the same trouble for some time. Lets make that new way standard and improve from that on, now." This new way will now become a standard. Lots of people having new feature request, because this old standard can do this cool feature the new standard can't, so lets in-cooperate that into the new standard. And so on, and so on. And the wheel will start over again with a new person.
BTW, you can apply the same pattern to programming languages. Remember why and how PHP started? Because Perl was a go to at the time, but it was to complicated for some people. Then came Ruby on Rails.
If you don't actually learn Markdown, how do you expect to be able to write it?
Titles go from # to ###### (<h1> to <h6> if you like)
Bold is * * bold* * (without spaces), italic is * italic*
Is it really that hard to learn once and for all?
All that's going on here is that you're used to one syntax, and not to the other. If one is used to both, markdown is quite nice.
Also:
> Am I the only one that actually wrote a script to convert HTML to Markdown just so I can create those silly README.md files without having to remember some awfully inconsistent syntax?
HTML is valid markdown - you can just use <b> and <h3> and so on, there's no need to convert them to markdown equivalents.
http://www.markdowntutorial.com
I stopped reading your comment there. It indicates that you're either lazy or not too bright.
A 5 year old can pick up 95% of Markdown in 5 minutes. Yes, and that includes bolding and italicizing text.
GitPitch was indeed launched with developers in mind. Devs often need to present and promote their work. Having worked as a software consultant for over 20 years I can attest to this. And with the rising popularity of tech meetups and conferences now more than ever making it easy to clearly present concepts, designs, etc. right alongside the actual code in your repo is a big win.
GitPitch is also seeing wide adoption across academia, particularly as a tool for delivering course materials, again right alongside the code.
As a final note, you mentioned a perceived drawback. GitPitch presentations are indeed automatically made available online just as soon as you git-commit and push to GitHub, GitLab or Bitbucket. But if you really want to host the presentation on your own domain or under your GitHub pages a fully self-contained bundle for your presentation is available for download with one click. You can then take the contents of that bundle (HTML/CSS/JS) and deploy it on your own Web server. No problem.
Okay, you peaked my interest. This is the slide (built via PowerPoint) that I use to explain a nested loop structure to CS1 students [1]. Explain to me, as an academic mind you, how I can recreate this without learning CSS animations / JS magic?
If I have to, that's fine, but all I'm asking is to make a circular motion animation. I'm demonstrating I can do that in 6 steps with PP; if technical knowledge is necessary, then it's a bit of a lie to say it can be widely adopted to academia.
[1] https://gfycat.com/UnselfishAcclaimedJellyfish
https://github.com/gitpitch/gitpitch/wiki/Image-Slides
Or if you have a series of images that combined present some kind of animation or workflow you can use those images as an animation sequence as described by Image Animation in the Wiki:
https://github.com/gitpitch/gitpitch/wiki/Image-Animations-W...
Here is a link to a sample presentation that makes use of this feature:
https://gitpitch.com/gitpitch/microservices-architecture
Do keep in mind, GitPitch is not trying to offer everything PowerPoint is capable of. Far from it. But it is trying to offer just enough, in a lot of use cases. But perhaps not yours.
In the graphic, we create two separate variables. The outer loop is only controlled through the X variable, meaning only when X is greater than or equal to 3 does it cease. If X started at a higher than 3 number, it doesn't run at all, but that's not the point of the example. The confusing part comes with the Y.
Y is the controller of the inner loop, and only gets incremented when the Y loop iterates. Once the inner loop completes, it still has 2 more instructions to execute (that belong to the outer loop), so it does them. That last line resets the Y variable, so that it can run the inner loop the next time.
It's actually a good question I ask as a follow-up. Suppose I delete the "y = 0;" line, how does that change how the loop behaves?
At no point does my X variable manipulate my Y variable directly (through loops yes, but not like y = x * 2). Like if I went through an old fashion phone book or dictionary, there are 26 letters (outer loop), but each letter has a varying number of words (inner loop). Then it'd read something like
https://github.com/gitpitch/gitpitch/wiki/Slide-Direct-Links
If you want to disable this feature you can disable it using your PITCHME.yaml config file, just add:
history: false
This avoids having to click back through each slide.
Git is a magic word and GitHub knows it. Spell 'git' to summon professionals of all kinds. But by releasing GitPeach, GitHub wants to show that its average 'dev' user needs help with making presentations. Is that really a problem? Presentations? Thanks, I don't need GitHub for presentations.
What's next? GitCodesForYou? LetGitThink?
> it does not work without GitHub
Firstly - it currently works with GitHub, GitLab and BitBucket.
Secondly - it reads one markdown file from the repo. It could work from any url if they wanted it to.
> But by releasing GitPeach, GitHub wants to show
Let's assume thats some kind of weird autocorrect, and you meant GitPitch. Either way, GitHub isn't releasing anything here. It's a third party, who use GitHub to host the source code for the tool.
It lets you use Markdown to generate Html, Docx, Pdf, every other markup, and off course Presentations just like gitpitch.
http://pandoc.org
It can also easily be extended to support more features.
See http://andreineculau.github.io/go-remark/?//andreineculau.gi... Source: https://github.com/andreineculau/go-remark
For an example, see .slide source [2], and the presentation result [3].
[1] https://godoc.org/golang.org/x/tools/cmd/present
[2] https://github.com/golang/talks/blob/master/2012/chat.slide
[3] https://talks.godoc.org/github.com/golang/talks/2012/chat.sl...
(I'm one of the mods here.)
https://github.com/gitpitch/gitpitch/wiki/Slideshow-Offline
If it is so important to be able to find the pitch of a github repo, just put the link in README.md.
Running a couple lines in bash gets me latex formatted PDF handouts of my slides via pandoc.
When you view a GitPitch presentation it is rendered by the reveal.js library. GitPitch simply provides a new way of delivering presentations that are powered by reveal.js that works seamlessly directly within GitHub, GitLab, or Bitbucket.
If you prefer to use the reveal.js library directly, or use their hosted service slides.com or any other of the great tools mentioned in this thread, then go right ahead. There is something for everyone. GitPitch offers it's own unique approach. And for some, that makes the most sense.
Code: https://github.com/gnab/remark
Personally, I'm very fond of it, due to it's preview/note-showing feature which you will enjoy, after pressing C (clone) and P (presenter-mode) in the cloned window.
As with many alternatives, it doesn't pollute your slides with any unwanted ads or external dependencies.