6 ms·
GitHubDocs – Open source SPA built using Markdown docs in your GitHub repo
- numbsafari 9y agoWhy would I want an SPA for documentation?
- mrvautin 9y agoWhy not?
- whorleater 9y ago1. 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"
- mrvautin 9y ago1. 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.
- stephenr 9y ago> Hardly any websites work without JavaScript these days. [Citation required] > Nonsense That doesn't really refute the claim.
- dictum 9y ago> 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)
- detaro 9y ago> 3. Nonsense. What tangible benefits do you see?
- detaro 9y agoBecause 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)
- spilk 9y agoPlus 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.
- stephenr 9y agoIndividual 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.
- deburo 9y agoI don't understand this. I am able to bookmark the page (http://host#fragment http://host#fragment), and it serves me the right page, no? Ex: https://githubdocs.markmoffat.com/#Erant-ventorum-aliter-esse-pervenientia-mutua-numquam https://githubdocs.markmoffat.com/#Erant-ventorum-aliter-ess...
- deleted 9y ago[deleted]
- always_good 9y agoYours works by accident. Try this one: https://githubdocs.markmoffat.com/#Suam-aera https://githubdocs.markmoffat.com/#Suam-aera Of course, this is just a bug. SPAs certainly can be bookmarked.
- stephenr 9y agoThey 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.
- fenwick67 9y ago"Why not" is a terrible reason to add complexity to anything.
- petepete 9y agoSearch 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.
- mrvautin 9y agoThanks. I will check it out.
- deleted 9y ago[deleted]
- deleted 9y ago[deleted]
- pspeter3 9y agoWhy not use gitbook?
- stephenr 9y agoGenuine question: isn't that targeted at writing (and then publishing) actual books, rather than relatively (compared to a book) short documentation?
- pspeter3 9y agoIt is but it is also used for documentation. The Redux documentation use gitbook for example http://redux.js.org/ http://redux.js.org/
- thinkxl 9y agoOr GitHub's wiki
- pspeter3 9y agoI 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 9y agoSeems 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/ https://githubdocs.markmoffat.com/ [1] https://githubdocs.markmoffat.com/#Erant-ventorum-aliter-esse-pervenientia-mutua-numquam https://githubdocs.markmoffat.com/#Erant-ventorum-aliter-ess...
- xj9 9y agopls 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 9y agoSoon 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 9y agoAt 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 9y agoThe 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 9y agoAlternatively, 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.
- thinkxl 9y agoI 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 https://news.ycombinator.com/item?id=13315444 - Do you really want a single-page application framework? https://news.ycombinator.com/item?id=12956059 https://news.ycombinator.com/item?id=12956059 - The Disadvantages of Single Page Applications (2014) https://news.ycombinator.com/item?id=9879685 https://news.ycombinator.com/item?id=9879685