This is the main problem with web that people are raising.
Something as simple as documentation, that obviously should be a collection of static pages, is now a web application.
You don't need React, Vue, Angular, Ember, etc. What you're building now might not be web application.
Rust's documentation uses javascript for search but it uses no js framework at all. IIRC the normal experience works without any JS. In fact it doesn't even use any traditional js tooling, allowing people to contribute to rustdoc without having to install npm.
> allowing people to contribute to rustdoc without having to install npm
In the meanwhile, the crates.io team doubled down on Ember to attract front-end developers while presumably alienating a lot of other potential contributors.
Maybe I'm wrong, but vue.js is just frontend js. So in theory it can be used in pair with a static server on backend side.
So the problem here is surely not vue.js
The Windows 95 ".chm" help pages [1] were basically HTML pages, displayed in an application embedding Internet Explorer. IIRC this lead to login exploits (since the login screen was able to show help pages).
Before that we would have had lovingly troffed manuals, checklists, man pages, binders, and libraries of books sitting in our spacious cubicle. Embrace tradition imo!
There is no way anyone in their right mind would call main.js[1] easy to understand. It's basically complete chaos. Guillaume is making a good effort to clean up this inherited code slowly, but the interactions are still kind of broken and will be until this code is rewritten in a sane pattern such as MVU. FWIW, I have been working towards this for the past year.
You're right, as a whole it's not trivial. I remember reading the search part and found it not particularly hard, but I missed the big picture. Thank you for your work!
Since JS is required for those features (in the absense of a dynamic server backend), who cares whether it's bundled Vue.js or some hand-rolled vanilla JS?
I'm sure some care. I'm not sure many care, and I'm even less sure that they have any valid reason to care besides a knee-jerk "bloat" reaction.
If you look at the chain of comments, I'm saying that you can do with vanilla JS what you can do with Vue, so you don't "need" Vue. You're free to use it of course, but it's not "necessary". That was my main point.
> I'm even less sure that they have any valid reason to care besides a knee-jerk "bloat" reaction.
I totally agree! Especially if the team is already used to Vue or React or whatever and it will help them produce a higher quality product than going with something they don't know. I do value light software, but not to the point of stupid light [1], and not implementing feature because "Vue is bloat" would be an example of stupid light software.
There is a quantitative difference between a folder with some HTML + other assets and a project that requires a specific v8 runtime wrapper and its own build pipeline to generate the aforementioned artifacts.
My grandmother knows how to (and does) use the former. The latter guarantees I'll always have a job.
It's a documentation generation tool whose only goal target is official macOS development enviroment, on which all of this is handled automatically via the "compiler" bundled in XCode.
It's not some generic tool handed over for random projects to write their documentation on...
But even if it was, setting up a build pipeline is trivial for developers including grandmothers who code (it's not intended for their non-coders, whether they are grandmothers or not). Most teams already have similar pipelines for their documentation anyway, whether it bundles JS or not, and are already processing it with Node (e.g. JSDoc), Python (e.g. Sphinx), Java equivalents, and so on.
We don't use frameworks because they're required, we use them because they make dev lives easier and provide some common ready-made structure and functionality.
Strictly speaking, nothing ever requires a framework: after all, any framework is just code - and you could always write vanilla code to achieve the same functionality (up to re-implementing the whole code of the framework yourself from scratch).
This comment does nothing except state the obvious. ;P
The parent I'm responding to listed very simple examples that in no way necessitate a framework; of course frameworks can be useful for larger scaffolding and the like.
Thanks for clarifying, but are you sure? On the very page I mentioned, there's a link at the bottom: "Distributing Documentation to External Developers" and on that page it says:
"Share your documentation directly with Xcode users or host it on a web server."
Sounds to me like you build that documentation using the SwiftUI-like DSL, but it is distributed in the DocC package.
I read that whole article as "Github is unuseable for open source projects."
Seriously I get that people like Github, okay. But the way everybody is rushing to hand Github a monopoly not just on git hosting but the entire open source workflow is terrifying.
Aren’t all the problems solvable with a few scripts? The complaint seems to be that the archival format isn’t directly compatible with GitHub pages, and it’s stored in an odd folder, but should be possible to copy and extract out into any format using a script.
Doesn't look like it, see https://github.com/JosephDuffy/DocC-netlify which is the example linked in the article. The author treating the archive as a folder with static files in it, and using the URL rewriting DSL to do full service.
What HTML and CSS? It’s a giant web application, are you goings to crawl the entire thing using puppeteer to extract the content then make up pages and synthesise links?
All the HTML page does is load the JS application, and tell you to get fucked if you don’t have js enabled.
Ok, last comment, not sure I want to argue about this. It looks like an application, but it's not. It's a bunch of HTML, CSS and JS packaged in a specific way (using its own spec), but it's not an executable. It's just arcane. It can be opened and expanded in the same way that a .epub book can be opened and hosted on a static website like GitHub Pages. It's not obvious or easy, but it can be done.
Apple chose a packaging format, and they packaged it. It's not an executable. EPUB is a closer example. Can be opened, can be parsed, can be re-packaged to whatever format anyone wants.
The content of the rant is stupid, in fact, if you read this post, DocC is "unusable," with "github" and the specific workflow of the author, not specifically with "open source" projects.
But, that being said, there are countless documentation from code formatter, I don't really see what particularity DocC has to be considered as excellent.
There's also a large, and probably growing number of open source projects hosting documentation on Netlify/Vercel. Somebody's definitely going to use it, and if it has enough other advantages, people will notice and migrate. And GitHub might one day support path-based SPAs, it's old news at this point. I still remember GitHub Pages being an https holdout for many years.
it doesn't work with any kind of static web hosting which is a shame given that it's all static content anyways.
The scripts could be adapted to work without requiring URL rewriting on the server.
The second complaint is about styling which currently doesn't seem possible. If you're a project of any considerable size, you probably will want your docs to be branded in some way which is not possible either ATM.
Those are certainly issues, but note that they have nothing to do with the alleged main point of the article, in that they make it unusable for open source projects. Quite the opposite, they are unrelated to the licensing at all.
I think it is a fair criticism to point out that the author seems unhappy about a non-OS website yet they somehow think this is an OS issue.
The problem is that DocC is incompatible with the current tools that many Open Source projects use.
Sure, you could use DocC for an OS project and set up your own server to host it. It's probably pretty cheap to do that on a VM. It would require just a little bit of learning about web hosting and would require minimal maintenance.
But why would anyone do that when Github pages is completely free, requires zero maintenance, and everyone knows how to use it already?
A lot of small Open Source projects currently use Github + Github pages for hosting docs because it is such a convenient offering. If you want to use DocC, you have to look for something else.
I have hacked "URL rewriting" on Github, bu having a custom 404 page, that rewrites the URL as a query parameter. And then in the app just use the history api to take that query paramenter and replace history without an actual reload.
I've deployed SPAs on GitHub Pages before, and you can just rename the index.html to 404.html and the site will function just as normal with no modifications.
I think that’s an arbitrary line you’re drawing. Every webserver does some URL rewriting, otherwise you wouldn’t be able to to use /docs, /docs/ and /docs/index.html. The difference is just that this requires some more custom rewriting rules to facilitate being a single page app.
I personally even disagree with that architecture, I think it’d be better to pretender the content for all pages (like, e.g., Gatsby does) but I wouldn’t call it not a static page.
The problem here is GitHub Pages doesn't support path-based SPA, i.e., it doesn't support rewriting non-asset URLs to site index. I won't argue for or against using an SPA (without SSR, too) for documentation, but this is certainly one of the most annoying limitations of GitHub Pages in 2021, generally speaking.
It's a hacky workaround, but by naming your HTML file 404.html it functions just as a regular SPA supporting webserver would. It does send a 404 where a normal webserver would send a 200, but it doesn't cause any problems from my testing.
I have noticed multiple times that when I navigate to some documentation site brave shows this bar that page does not exist and whether you want to access it on archive.org. But the site below is perfectly functional.
I always thought that this was some weird server misconfiguration causing 404 even if content is available ... Never guessed it was a hack to enable SPA routing.
Static in this context means that requests by visitors have no influence on the site's content. As for Jekyll, it's a static site generator. The output is still static content.
Agreed. The only thing you'll miss out on are a few interactions with vue-router, basically your URLs will go from this:
foo.com/blah
To this:
foo.com/#/blah
The obvious reason being that without those URL rewriting rules the client would do a real HTTP request for "/blah" and problems ensue. Note that the problems won't actually occur until after the user tries to refresh the page or similar because the entire URL bar is being hijacked by window.location management.
I wish we had documentations in the form of man-pages even with diagrams as ascii art, and then everything is readable, searchable, highlighted, ...etc from the terminal. I don't want to pick my hands off my keyboard and pull the mouse (or touchpad, or using a thinkpad nip) just to view, read, and browse the docs.
Is setting up a (free) Netlify site really such a big barrier to entry? GitHub really has the community spoiled with their big bundle of free services.
Anyway, I suspect there’s a reasonably good chance for GitHub to pick this up eventually as a feature for Pages.
It’s still just statically generated HTML pages (+ some client side JavaScript). It only requires a webserver with a minimal amount of configurability for URL rewriting and redirects.
It's not about github. github is just the real world and most visible example, but the problem is general.
For most of my own small projects the docs are nothing but the README.md, and if the only way to make better docs required setting up a web server for each one just to host it's docs, they never will be more than the readme.
It's completely unreasonable to require a dedicated server to host some documents, which in themselves wouldn't and don't require any such thing.
Sounds like a good use case to support natively via cloudflare workers / their tool wrangler; which makes hosting less relevant. I know cloudflare is a no-go for many, but for the rest of us it makes sense. Could probably be hosted fully on their pages too?
Seems like a good opportunity for someone to setup a https://readthedocs.org like website that works with this new format. Maybe even readthedocs could start working with it.
I suppose there’s merit in the complaints from an OSS contributor’s standpoint, but yes, it seems like the current target market is companies with closed-source SDKs.
Which isn’t a bad thing if this is MVP1, and I do expect improvements in the future.
This is the main problem with web that people are raising. Something as simple as documentation, that obviously should be a collection of static pages, is now a web application.
You don't need React, Vue, Angular, Ember, etc. What you're building now might not be web application.