
GitPitch – Markdown Presentations for Devs on GitHub and GitLab - gitpitch
https://github.com/gitpitch/gitpitch
======
didibus
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.

[http://pandoc.org](http://pandoc.org)

It can also easily be extended to support more features.

~~~
radix07
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](https://pandoc.org/MANUAL.pdf)

------
xkr
Second slide of their hello-world example:

    
    
      <!-- .slide: data-autoslide="2000" -->
    
      ### No more <span style="color: #666666">Keynote.</span>
      ### <span class="fragment" data-fragment-index="1" data-autoslide="2000">No more <span style="color: #666666">Powerpoint.</span>
      <br>
      ### <span class="fragment" data-fragment-index="2" data-autoslide="3500">Just <span style="color: #e49436">Markdown</span>. Then <span style="color: #e49436">Git-Commit</span>.</li>
    

Doesn't look like a simple markdown for me.

~~~
dheera
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?

~~~
blipmusic
You seem to miss the idea of Markdown.

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.

~~~
dlandis
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.

~~~
blipmusic
How simple, though...?

    
    
        # title
    
        - item1
        - item2
    
        some paragraph with an *italic* word
    
    

->
    
    
        <html>
        <body>
        <h1>title</h1>
    
        <ul>
          <li>item1</li>
          <li>item2</li>
        </ul>
    
        <p>some paragraph with an <i>italic</i> word</p>
    
        </body>
        </html>

~~~
Chiguire
You could have simplified that to:

<title>title</title>

    
    
        <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.

~~~
dheera
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.

~~~
accordionclown
you have a point.

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 &rsquo; which needs to sit in the middle of
every contraction. like this:

    
    
      &ldquo;if you don&rsquo;t have it, you&rsquo;ll still have something...&rdquo;
    

ick. no thank you.

~~~
dheera
"if you don't have it, you'll still have something ..."

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.

------
gitpitch
Hi @mankash666, thanks for your feedback.

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.

~~~
tsumnia
> 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.

[1]
[https://gfycat.com/UnselfishAcclaimedJellyfish](https://gfycat.com/UnselfishAcclaimedJellyfish)

~~~
chatmasta
Totally unrelated, but doesn't that graphic become innacurate when the inner
loop consumes an array of size size greater than that of the outer loop?

~~~
tsumnia
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
        }

------
mankash666
Reveal-Md is similar: [https://github.com/webpro/reveal-
md](https://github.com/webpro/reveal-md)

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.

~~~
podiki
Or (for those on the Emacs side of the old holy war), directly from org-mode:
[https://github.com/yjwen/org-reveal](https://github.com/yjwen/org-reveal)

------
geraldbauer
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](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](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](https://github.com/geraldb/talks)

------
stephenr
Maybe it's the mercurial-using cynic in me, but this seems vary barely related
to Git, and much _more_ related to Markdown.

~~~
rwah
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.

What's next? GitCodesForYou? LetGitThink?

------
kensai
Please, don't take it for trolling or anything, but I was kind of blasted away
by the color selection of the GitPitch name in its official page. Reminded me
of a certain site right away!

------
haspok
I'm afraid the organization logic is totally upside down. I would like to have
all my "pitches" in a single repo, possibly modifying some of them slightly in
branches - not one pitch per repo, or even worse, one pitch per branch (???).

Having a default PITCHME.md is convenient, but not if it is the only possible
way. What's wrong with adding a filepath after the branch in the url?

~~~
gitpitch
If you would like to have all of your "pitches" in a single repo you can
absolute do that. As described in the Wiki:

"Sometimes you may find yourself wanting to build a series of related
presentations within a single branch. Collectively these presentations may
share common assets such as images, backgrounds, and even custom CSS styling."

For details see the following page in the GitPitch Wiki:

[https://github.com/gitpitch/gitpitch/wiki/Asset-
Sharing](https://github.com/gitpitch/gitpitch/wiki/Asset-Sharing)

You might also be interested in support for modular Markdown which allows you
to share not just assets but Markdown snippets across multiple presentations.
See here:

[https://github.com/gitpitch/gitpitch/wiki/Modular-
Markdown](https://github.com/gitpitch/gitpitch/wiki/Modular-Markdown)

~~~
haspok
Thanks for the reply, much better. I still don't get why the filename has to
be PITCHME.md, though :)

~~~
gitpitch
PITCHME.md is a convention. Simple and memorable just like README.md.

------
rorosaurus
I would love to see a version of this where you can deploy your slideshow to
your own Github Pages, with no external dependency on GitPitch.com.

~~~
gitpitch
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.

------
shurcooL
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].

[1]
[https://godoc.org/golang.org/x/tools/cmd/present](https://godoc.org/golang.org/x/tools/cmd/present)

[2]
[https://github.com/golang/talks/blob/master/2012/chat.slide](https://github.com/golang/talks/blob/master/2012/chat.slide)

[3]
[https://talks.godoc.org/github.com/golang/talks/2012/chat.sl...](https://talks.godoc.org/github.com/golang/talks/2012/chat.slide)

------
izacus
Since conferences usually have flaky and broken wifis, does it work well
offline?

~~~
gitpitch
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:

[https://github.com/gitpitch/gitpitch/wiki/Slideshow-
Offline](https://github.com/gitpitch/gitpitch/wiki/Slideshow-Offline)

~~~
izacus
That's great to hear, will try it out for my next talk :)

------
autarch
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.

~~~
gitpitch
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.

~~~
gitpitch
Shoutout to reveal.js added to GitPitch README and Wiki. Credit already exists
on the GitPitch.com website.

------
andreineculau
I have been doing this for years with remark. Works on any git service,
because it only needs a url to a markdown file.

See [http://andreineculau.github.io/go-
remark/?//andreineculau.gi...](http://andreineculau.github.io/go-
remark/?//andreineculau.github.io/go-remark/remarkjs.md) Source:
[https://github.com/andreineculau/go-
remark](https://github.com/andreineculau/go-remark)

------
rawland
One more alternative: [https://remarkjs.com](https://remarkjs.com)

Code: [https://github.com/gnab/remark](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.

------
FranckP
If you need advanced features such as graphs and charts, you should have a
look at [https://www.neomobili.com/products/slidium-markdown-
presenta...](https://www.neomobili.com/products/slidium-markdown-
presentation/) The question is : can we use gitpitch with it? Both seems to
use reveal.js internaly

~~~
gitpitch
That looks very nice. Just fyi to anyone reading here it also worth mentioning
that GitPitch has built-in support for graphs and charts powered by
chartsjs.org.

See the GitPitch wiki here for details:

[https://github.com/gitpitch/gitpitch/wiki/Chart-
Slides](https://github.com/gitpitch/gitpitch/wiki/Chart-Slides)

------
andrewguenther
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.

~~~
gitpitch
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:

[https://github.com/gitpitch/gitpitch/wiki/Slide-Direct-
Links](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

~~~
redonkulus
You could use replaceState instead to change the URL but leave the history
intact. [https://developer.mozilla.org/en-
US/docs/Web/API/History_API...](https://developer.mozilla.org/en-
US/docs/Web/API/History_API#The_replaceState\(\)_method)

This avoids having to click back through each slide.

------
chiefalchemist
What I'm seeing here is a simple and easy way for presenting step by step
instructions. Imagine, here's Product X (e.g., class) and he's how to use it
(or at least get to know it in a very bite size way). Sweet.

------
SixBitProxyWax
I pretty much get the same result without needing a third party service by
using a single Jekyll template with GitHub pages.

Running a couple lines in bash gets me latex formatted PDF handouts of my
slides via pandoc.

------
tajen
The concept was invented years ago with Reveal.JS. What's wrong with it?
[http://lab.hakim.se/reveal-js](http://lab.hakim.se/reveal-js)

~~~
gitpitch
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.

------
willtim
I've been doing this for years using pandoc and beamer.

------
aamederen
Why not use something like Google Slides and try to make it via md?

If it is so important to be able to find the pitch of a github repo, just put
the link in README.md.

~~~
Jraf
something like that ?
[https://github.com/googlesamples/md2googleslides](https://github.com/googlesamples/md2googleslides)

------
jduckles
Cicero [http://cicero.xyz/](http://cicero.xyz/) does this using reveal.js

------
Zekio
Tried to go fullscreen in a presentations and it couldn't exit the fullscreen
mode again, not a fan...

------
alihcevik
Awesome! But I can't use it if I need to make my slides public. Do you support
private repositories?

~~~
gitpitch
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.

~~~
dang
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.

(I'm one of the mods here.)

~~~
gitpitch
Sure. My apologies.

------
Romanulus
Marketing instincts came through; Gitch is waaaay to close to ginch.

------
ubitakken
Add a markdown file to your repo and get a presentation. Very nice!

------
MaxLeiter
Can the topic be changed to include BitBucket like the README does?

~~~
gitpitch
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.

------
orschiro
It would be cool to also "pitch" Github Gists. :-)

~~~
gitpitch
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](https://github.com/gitpitch/gitpitch/wiki)

~~~
orschiro
Thanks!

------
sidcool
Very useful. Hope it is adopted as well ad README.md

------
LeicaLatte
Very nice.

