I committed the website source I have been working on and then linked the Documentation section to one of the help Markdown files, i.e. http://reboldocs.brianotto.com/insert (which is really insert.MD), and Github now renders any Markdown I add there to HTML, automatically creating a documentation page for me. I had been working on some small code examples, before starting on the website, and so this what you see listed there.
So it appears like we could use the already existing MD files for two purposes, the interpreter help and the website documentation. One thing I did have to do was add HTML comments (i.e. <!--) around the interpreter help section so the website wouldn't render them. Would it be easy to ignore these by the interpreter?
Anyway, this basically gives us the ability to have URLs named after any of the documents in that repository. Also, the content is controlled by Github, and so the repository can be forked and anyone can contribute using only a markdown editor and sending a PR. There is no need to install Jekyll or the likes.
However, there is still one issue I am looking into and that is the ability to maintain the website header and footer on each of the documentation pages and to have some kind of navigation display. I think you can create a template that all MD files get rendered in, but still looking into this ...
It looks extremely promising...and you apparently know what you're doing, as I loaded it on a cell phone and it looked good there too!
It might be a little limiting if the page is slaved to exactly what GitHub is willing to serve up. I know it would be a bit latent if the server requests the GitHub data for MarkDown preprocessing, and they probably have some throttling that comes into play. (?) But I don't know if enough people are reading Rebol online docs right now to run afoul of it.
One could also have the server keep an enlistment of the git data and periodically sync it with GitHub, and do the markdown rendering locally, as I imagine that's kind of a commodity thing. FWIW, there is a mostly-working "MarkyMark" by @rebolek(which hostilefork.com uses, but I haven't really touched the site in a long time...I notice errors from time to time in the generated HTML and have been too lazy to worry about fixing it).
I guess the main thing being having the flexibility to adjust the presentation if a cool idea comes up. So looking for the best of both worlds, I guess? This seems great so far.
I know I've been pitching the black and white strongly...and I want to extend that pitch to the code samples.
There are three themes on @rgchris's Twitter, Etsy, and S3. You can change the theme by pressing a key:
L gets you the light theme
D gets you the dark theme
G gets you the gray theme
Of these, I find the gray theme the most compelling by far. In a language with no keywords, I think that bolding set-words is a much more striking move...and keeping it clean and clear of distractions.
We focus very hard on trying to make the code something that would look good coming out of a typewriter. And I think there's an air of seriousness and non-amateurishness when one doesn't use circus colors on one's code. I might even suggest it would be neat if the code appeared to be on a sheet of paper and having come out of a typewriter.
Would recommend Google Code Prettify which will mark up a <pre class="prettyprint lang-rebol"> block with e.g. <var class="dt-string"> tags to differentiate values. An example of it in use: Form Date ('Prettify' includes at the bottom). Can easily be adapted from colour->b/w by adapting the style sheet. This should spare the effort in pre-colourising code samples.
All kidding aside, if you like the look of that typewriter then we would have to find a smaller one (in height). This one is taking up way too much space on the page. It's also going to be tricky to get it to display correctly on mobile. I had to use some pretty ugly positioning code to get the "paper" to line up just right... and I haven't checked yet, but I imagine this isn't going to fly on mobile. So it will take a fair bit of trial and error to get something working correctly on all screen sizes.
Keys aren't really part of the message. Nor are typewriters. It could be any kind of slick looking or interesting looking machine that fed something more paper-like and had that very bold, striking, monochrome scheme to it. A more futuristic thing that felt like it matched the logo, a thermal printer that looked like it was made by Tesla or something.
The download button or emscripten "Take an Online Tutorial Right Now" buttons might be exceptions to the theme, breaking out with some eye-catching color.
Anyway, just trying to set up some design language here. It's not totally important that you worry about getting all these things right, I actually spec'd a website once that people came and did quite a nice job of later:
If it's working, and all the rules of the sizes and reactive layouts are known, designers are pretty good at this kind of thing. I might even at some point re-install illustrator and photoshop and such on the Surface Book (if I can figure out how to get Adobe to activate the pre-subscription CS6 disc again) and take a crack at it.
Sounds good to me, the typewriter was a fun exercise to do, but I'd prefer someone with more design experience than me handle that type of stuff. I can certainly make it work on the different screen sizes after something has been fleshed out.
I'll get back to looking into template support on Github pages ...
No need, I'd rather keep the MD files clean anyway and just store the header in a separate file that gets included by Github... and it looks like this is possible, yah! I was just able to change the template for the MD files without modifying them. So I should be able to wrap all those MD files in the demo site's header / footer / nav over the weekend.
I made some progress tonight and got the documentation pages to display in a template that includes the site's header, footer and a custom nav. I did have to do this using Jekyll, and so we can't get away from using it completely. Here is what the page is looking like now.
It's working out rather nicely, and so the next steps are ...
Tweak the layout to work better in mobile
Get the breadcrumbs generating dynamically
We should also decide on a color scheme for the code blocks. Also, for Jekyll to recognize the MD files and wrap them in the template that is being used on the Documentation page, they all have to sit in a sub-directory. I created /docs/3.0/ for this purpose and moved one example file there (insert.MD), but they all need to be moved there eventually. Is that going to be a problem? I wasn't sure if you had anything dependant on them sitting in the root of the repository.
The help docs location is configurable somewhere .. just don't recall where exactly.
But we can repoint to either the new docs location if we can also point back to github for adding comments
That's great!!! Now we just have to kind of...make that be a more sensible category and curate that content a bit better. We should come up with a format where the summary lines are short enough to fit in blurbs, so if you have standards for that.
(P.S. since each of these feature conversations could go on for a while, don't be afraid to top-post new topics...in this case, it might have fit under Backdating News Articles. Otherwise "Rebol Docs Experiment" thread will get very long...)
Pursuant to that...next remark on a new thread....
Yea, I still need to experiment with that, and figure out what works. It will probably be something along the lines of how newspapers do it, where they summarize the article in a lead paragraph, but with a maximum number of characters (in a standard font size) so we don't overflow the box height. I will post my results in the Backdating News Articles thread.
I did a major re-structuring of the Documentation page last night to support Jekyll collections, and it now builds itself automatically from the metadata in the MD files. So adding a new section, chapter or page is just a matter of committing a new MD file now, there is no need to modify any of the underlying HTML / CSS / JS. Same if you want create a whole new version of the documentation. The breadcrumbs now load the correct path too, based on the page that is loaded. So it's much more automated now.
Anyway, I'll go into more detail on exactly how to configure things in a new Topic, once I get a few more updates made. I want to convert the roadmap section into the same format first, and there are a few things I want to try with the archived documentation too, to see if I can get some of it loading into the site.
Sounds like the fluidity we are looking for, and staying away from getting entangled with a CMS! Good plan.
We should also take advantage of GitHub's online editing too, to make simple corrections. Ideally trusted parties would have commit access directly, to not have to go through a PR process to get things fixed.
This also speaks to the importance of separating out the code for the site from the augmented documentation.
The auto-generated portion of the help markdown should ideally not be part of the markdown file. If it's too slow to spawn a Rebol and ask it to fetch the HELP, then perhaps a nightly cache could be built...?
There's some risk of the information getting out of date with the function spec. I wonder if maybe changes to the help could be detected, and compared against a last date in the examples, to generate some kind of warning?
