GitHubDocs – Open source SPA built using Markdown docs in your GitHub repo(npmjs.com)
npmjs.com
GitHubDocs – Open source SPA built using Markdown docs in your GitHub repo
https://www.npmjs.com/package/githubdocs
7 comments
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.
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.
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)
Why would I want an SPA for documentation?
Why not?
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)
- 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)
Plus it's (more) complicated to wget mirror it to reference while offline. Being in a public github repo makes it easy but I've run into issues trying to take older frames-based "SPA" documentation sites offline that aren't explicitly downloadable.
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"
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"
1. Hardly any websites work without JavaScript these days.
2. That would imply you like your documentation entirely on one page. Anyway, that's why there is a search box...
3. Nonsense.
2. That would imply you like your documentation entirely on one page. Anyway, that's why there is a search box...
3. Nonsense.
> 1. Hardly any websites work without JavaScript these days.
Got to be that guy: that's a circular argument. Other websites are doing X, hence you should do X too.
It's as much an argument for docs-as-SPA as it's for having a large Outbrain ad with a picture of some skin disease in your docs.
(Disclaimer: I don't hate web apps that don't work without JS — I build them too. But a page of text shouldn't require JS. You can ship the JS-only version as a separate website, but don't force all users to use it)
Got to be that guy: that's a circular argument. Other websites are doing X, hence you should do X too.
It's as much an argument for docs-as-SPA as it's for having a large Outbrain ad with a picture of some skin disease in your docs.
(Disclaimer: I don't hate web apps that don't work without JS — I build them too. But a page of text shouldn't require JS. You can ship the JS-only version as a separate website, but don't force all users to use it)
> Hardly any websites work without JavaScript these days.
[Citation required]
> Nonsense
That doesn't really refute the claim.
[Citation required]
> Nonsense
That doesn't really refute the claim.
> 3. Nonsense.
What tangible benefits do you see?
What tangible benefits do you see?
"Why not" is a terrible reason to add complexity to anything.
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.
That's why not.
I don't understand this. I am able to bookmark the page (http://host#fragment), and it serves me the right page, no?
Ex: https://githubdocs.markmoffat.com/#Erant-ventorum-aliter-ess...
Ex: https://githubdocs.markmoffat.com/#Erant-ventorum-aliter-ess...
[deleted]
Yours works by accident. Try this one: https://githubdocs.markmoffat.com/#Suam-aera
Of course, this is just a bug. SPAs certainly can be bookmarked.
Of course, this is just a bug. SPAs certainly can be bookmarked.
They can if the feature is implemented by the SPA framework/library/whatever, and if the JS loads and if there aren't any bugs (e.g. imagine a bug that means a fragment with an unexpected character can't be loaded).
Conversely, static HTML links (either links to id/name fragments in a large file, or links to specific pages if using separate files) almost can't fail, and it's incredibly unlikely a SPA would be even close to loading if regular static pages fail to load properly.
Conversely, static HTML links (either links to id/name fragments in a large file, or links to specific pages if using separate files) almost can't fail, and it's incredibly unlikely a SPA would be even close to loading if regular static pages fail to load properly.
Why not use gitbook?
Genuine question: isn't that targeted at writing (and then publishing) actual books, rather than relatively (compared to a book) short documentation?
It is but it is also used for documentation. The Redux documentation use gitbook for example http://redux.js.org/
Or GitHub's wiki
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.
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.
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.
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.
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.
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.
> 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.
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.
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.
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.
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
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
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...