GitHubDocs – Open source SPA built using Markdown docs in your GitHub repo

https://www.npmjs.com/package/githubdocs

by mrvautin • 9 years ago

44 32 9 years ago

npmjs.com

numbsafari• 9 years ago

Why would I want an SPA for documentation?

mrvautin3• 9 years ago

Why not?

whorleater• 9 years ago

1. Doesn't work without javascript enabled (it's text, why the hell do I need JS enabled to read it?)

2. Control + F doesn't work across pages, you'd need to first find the page you're looking for

3. Doesn't offer any tangible benefit beyond "being a SPA"

stephenr6• 9 years ago

Individual pages aren't bookmark-able with this, and to add insult to injury, loading the page with a fragment actually requires you to click a different in-page link, before clicking the one you wanted, to load that page.

That's why not.

detaro2• 9 years ago

Because being an SPA adds tons of potential for bugs that normal sites don't have. Case in point, your demo:

- required changing my adblocker settings to work

- Breaks the back button on the first page by adding instead of replacing the start page on the history stack

- changing pages doesn't reset the scroll position - you jump to somewhere in the middle of the new page if you switch pages while scrolled down

All of these can be fixed, but a non-SPA wouldn't have any of them in the first place. More work for what benefit exactly?

(While I'm listing bugs, the top of the content scrollbar is cut off/hidden behind the top bar, but that's not SPA specific)

fenwick67• 9 years ago

"Why not" is a terrible reason to add complexity to anything.

petepete• 9 years ago

Search doesn't look like it's working on the example site. When I pick a word at random from the text body and search for it there are no results.

mrvautin3• 9 years ago

Thanks. I will check it out.

pspeter34• 9 years ago

Why not use gitbook?

stephenr6• 9 years ago

Genuine question: isn't that targeted at writing (and then publishing) actual books, rather than relatively (compared to a book) short documentation?

pspeter34• 9 years ago

It is but it is also used for documentation. The Redux documentation use gitbook for example http://redux.js.org/

thinkxl2• 9 years ago

Or GitHub's wiki

pspeter34• 9 years ago

I personally don't like the Github wiki because you cannot transactionally commit to the repo and the wiki. I like adding documentation and code in one PR so it can be reverted together if need be.

t3f• 9 years ago

Seems to break my back button.

Going to [0] then redirects me to [1] and single presses of back continuously redirect from [0] to [1].

[0] https://githubdocs.markmoffat.com/

[1] https://githubdocs.markmoffat.com/#Erant-ventorum-aliter-ess...

xj9• 9 years ago

pls stop

you already have an html document and a browser that was made for browsing documents. why make another application that does the job of the application i'm using to access your documents?

for fun, it get it, but as far as something that i would actually use to read docs. no thanks.

kronos29296• 9 years ago

Soon this will become an offline app in electron which can be used as offline reference. Instead of a readme or html help. (Sometimes progress isn't a feature but a lack of)

guessmyname• 9 years ago

At this point, I think JavaScript programmers are just trolling.

The argument that "because others are doing SPAs, we have to do too" is invalid, the "others" are just either your friends or popular JavaScript programmers, and you follow them because you lack better arguments to go against this development technique. An SPA adds unexpected behavior to every web application, when we have spent years learning how a popular web browser behaves, people come to re-invent the wheel (back buttons, custom scroll bars, custom routers, and who knows what else).

Normally, I encourage people to learn and work on whatever thing they are interested in, not just technology-wise. But when you start promoting your project trying to make people use it as if it was good, well, then you have to expect some rants here and there. I am sure there is a lot of people who would disagree with me, and people who have good arguments for the development of an SPA, I would love to hear those arguments, I am being serious.

ameliaquining• 9 years ago

The primary argument in favor of SPAs is that otherwise the entire page and every resource on it has to be reloaded every time the user navigates, and the resulting user experience is vastly inferior to that of an SPA (or native app), especially for users on low-end devices and/or high-latency connections.

tscs37• 9 years ago

Alternatively, just don't load as much crap.

I've purposefully reduced my website to a minimal amount of HTML so that even on connections with high latency and low bandwidth, it loads quickly into the browser.

A lot of webapps I've seen lately could have just as easily been a lightweight, single PHP script with minimal styling and scripting.

That saves battery and bandwidth. SPAs only save bandwidth.

thinkxl2• 9 years ago

I see this argument everywhere, but, when the application is done properly, the reloading doesn't feel that bad.

Related past threads:

- Ask HN: Are there any solid arguments against SPAs in 2017? https://news.ycombinator.com/item?id=13315444

- Do you really want a single-page application framework? https://news.ycombinator.com/item?id=12956059

- The Disadvantages of Single Page Applications (2014) https://news.ycombinator.com/item?id=9879685

stephenr6• 9 years ago

every resource on it has to be reloaded every time the user navigates

Since when? Browser cache is a thing that exists.

especially for users on low-end devices and/or high-latency connections

I use an original iPad Mini (so basically the guts of an iPad 2 with a smaller screen) for occasional browsing. It definitely works better on simple, JS free pages.

I use said iPad Mini in Thailand. Regardless of our ISP provided line-speed, connections out of the country are always a throttling point for data. Having a regular browser-provided loading indicator (which can actually be intelligent and use things like the Content-Length header) is definitely preferable to some in-page JS (see above) spinner that gives zero indication of what % is loaded, or if it's hung, or whatever.

I am convinced at this point that SPA's basically exist to be 'portfolio' sites for front-end developers, the way designers would (maybe still do) create their own take on a popular app/website/etc and publish it, to show off what they're capable of.

mi100hael• 9 years ago

For this particular use-case (and other relatively static content in general) I'd always go with static pages a la Jekyll.

I was a SPA skeptic for a long time, but ultimately I've moved that direction, especially as frameworks continue to mature. For sites that aren't strictly static content, you're going to need to make some sort of AJAX call to update some component on the page. Using a framework like React that's purpose-built for that use-case is a lot cleaner and more maintainable than bolting together jQuery and DOM appends, especially as the number of calls & components continues to grow over time.

Plus, these days the UX is pretty much identical as interacting with a static site. React Router has natively-functioning history & link-able URLS. You can render a React page server-side just like a traditional web framework, so the initial page load doesn't take forever (which makes the site feel faster than a traditional web app because subsequent page loads are AJAX and partial DOM modifications). You can use React Native to build your SPA as a mobile app with real, native components, not just a web wrapper.

I can't believe I just defended React.

GitHubDocs – Open source SPA built using Markdown docs in your GitHub repo

Related Stories