reasonml / reasonml.github.io

Reason's documentation site

Reason Website

This code is used to generate https://reasonml.github.io. It pulls in files from docs/ and website/ to generate HTML files served on the site.

website/ contains the JS, CSS, images and other files (and some markdown files in blog which are separated from docs/; it's not too important).

cd website && npm install && npm run start to start the development server & watcher.

Don't use npm run build. It's mostly for debugging.

In the end, we spit out normal HTML with all but a few critical JS dependencies removed, including ReactJS itself. It's a full static website: super lightweight, portable, unfancy, but good looking. And it works with JS turned off!

Two special files:

• sidebars.json: lists the sections.
• siteConfig.json: some header and i18n configs.

During your development, most changes will be picked up at each browser refresh. If you touch these two files or blog/, however, you'll have to restart the server to see the changes.

Translations

The entire site can be translated via the Crowdin project. This repo only has the canonical English documentation. Don't manually edit things in i18n/.

Debugging

console.logs appear in your terminal! Since the site itself is React-free.

Building and Deploying

Changes from the source branch are automatically picked into master branch by CI and then published.

Building the Playground

cd website && npm install

For modifying the actual try playground source code, run npm run bundle-try-playground:dev to start a watcher. Once you're done, run npm run bundle-try-playground:prod once.

Building with custom BuckleScript/etc

To build the actual bsReasonReact.js, refmt.js, stdlibBundle.js, reasonReactBundle.js:

You'll need to have this repository and the BuckleScript repository cloned. These will likely be next to each other in the directory structure.

1. Inside the BuckleScript repository, follow the Setup guide.

2. Follow the Contributing to the BS Playground Bundle guide.

3. Run BS_PLAYGROUND=../../reasonml.github.io/website/playground/bs node scripts/repl.js

4. Inside the reasonml.github.io repository, run cd website && yarn

5. Then run, yarn prepare in the same place.

6. Finally, run node setupSomeArtifacts.js

If this command fails, ping @chenglou in Discord.

reasonml.github.io's Issues

Try https://microsoft.github.io/monaco-editor/ for Try playground

Debounce search keystrokes

Home page title broken for me

Can consistently repro in Chrome and Opera

The first time I visit the site the title is empty (confirmed by viewing the page source)
Then when navigating around and going back home by clicking the site logo the home page title is the title of the previous page.

Font size too large [discussion]

Looking at a few pages, I find the font size to be too large. It gets computed as '18px'. I took a look at the documentation for other sites and find the text to be more readable, where they have a computed font size of '16px'.

See Rust and Elixir

Try Reason: error obscures the lower part of the pane

If the error happens to be at the bottom of the pane, I guess you'll just have to live with it. (Alternatively you can add a few linefeeds at the bottom to push the code with the error up)

(Runnable) code example on front page

JSX parser error

This line produces an error
<span className="filter-label"><span>(ReasonReact.stringToElement "Has interface")</span></span>
Though if to format it manually like this, then it works:

<span className="filter-label">
     <span>(ReasonReact.stringToElement "Has interface")</span>
</span>

So as you can see from error, it complains that code contains some reserved BuckleScript keyword.

P.S.
Was redirected from BuckleScript team: rescript-lang/rescript-compiler#1874

Idempotent deploy

High pri. We'd like a deploy on master to be no-op (at least for the content itself) if the source isn't changed.

Playground: Add support for Standard Library Modules

It would be great to make use of the standard library in the playground.

let len = List.length [];

gets transpiled correctly into

var List = require("stdlib/list");
var len = List.length(/* [] */0);
exports.len = len;

Bucklescript Compilation Error
require is not defined

Memorize last Try snippet in localStorage

add full function syntax

labelled argument with renaming + default value

Playground extremely slow for anything past 10 lines of code

We should debounce. Though the bucklescript playground is super fast... http://bucklescript.github.io/bucklescript/js-demo/

Runnable code examples in tutorial

I suppose this might require rewriting the guide as a tutorial

Next page at the bottom of each section

I think it makes sense to add a next page button in the bottom right corner of each chapter/section. It gets tedious to scroll up (on small screens) after reading a section to find the next one.

Modules page edits

Before actually writing copy, I'd like to get feedback on a few suggested changes to the modules page in the language basics section.

Here's my proposal:

• Add an introduction that defines modules by what they do and makes clear that they don't just group related code, but also serve as the means of abstraction and generic programming. (This occurs later on in the current article, but perhaps beyond where most people would read.)
• Reorganize the example sections so that they are not grouped by language feature ("Module signatures", "Module functions") but instead by the purpose they serve ("Building abstractions", "Generic programming"). Add a callout to features from other languages that modules serve in Reason (templates, generics, type classes, etc.).
• Similarly, rename syntax-related sections from the language names ("opening a module") to the purpose they serve ("Using code from another module").
• Add more detail to the drawbacks section, which currently seems like a let-down after the rest of the article got you excited about modules. I'd like to add some more text on cases where modules aren't the right answer, and make clear that there are many cases where they are.

More prominent search

And maybe it let it float somewhere? It's nice to be able to stay on the page while searching

Quick start ideas

A few proposals for the quickstart section. I'm happy to do the work on these but wanted to get feedback first.

• Fold the editor config section into the JS and native pages, since people may otherwise neglect to go back and do it.
• Add some short hits to explain what the quickstart steps are doing ("Bucklescript is a ...", "OPAM is the ...") so people know
• Gather some possible error cases and what to do about them.
• Add a "Can't get it working?" section with where to get help. (Right now this is Discord, but that means that lots of people ask the same questions in there. It might be nice for the community to adopt a public, searchable, linkable place to provide definitive answers to common problems.)

Catch broken links

Permalink pages for blog posts

I have a feeling that links to individual blog posts are going to break because they're just fragment identifiers on a single page.

Example tweet that is doomed to break when the index page gets too long or we change the link format: https://twitter.com/wincent/status/901116644600172544

Ideally we'd have standalone permalink pages with stable URLs which will last "forever".

Should the menu titles be capitalized?

quickstart -> Quickstart

Overview needs an easy "your first program" section

The overview is nice because it gives easy syntax tips. However, I cannot see (as a non-Reason-programmer) how my first program should look. How can I print values? Do I need a main function? etc, etc

Middle click swallowed

On localhost this opens a new tab. On prod it turns into a left click.

cc @bassjacob

Routing breaks after a while of use

After clicking on some links really fast I eventually get SimpleEventPlugin.js:219 Uncaught TypeError: Cannot read property 'remove' of undefined and routing no longer works.

Some API docs are reaaaaally scaring looking

We should probably tweak the css for these

cc @jsdf

Playground eval timeout to avoid the infiniteness of infinite loops

Auto-evaluating an accidental infinite loop caused by some intermediate editing state kind of sucks. Not just because the whole tab freezes, but you'll also lose everything you did up to that point. Even with the new localStorage, a kill & refresh will just land you straight back into the same infinite loop of suckiness.

So yea.. Timeout good.

Reason Online Tool generates incorrect reason code from Ocaml

But this code is incorrect, compilers says:

Error: This pattern matches values of type string
but a pattern was expected which matches values of type int

Sharable Try links

We can encode the snippet in the URL in the simple case

Anchors for headings

So that we could link to sub-sections in e.g. this section: https://reasonml.github.io/guide/language/types

reasonml windows installation instruction

Hi, as one of OS - windows user, I've been tried the different solution for installing reason on windows.
As last and most successful way which works mostly out of the box
is that package ocaml-on-windows.
Full IDE(vscode) support including merlin, refmt and other tools:

What do you think, should we add that package to documentation? I think it will help a lot of window-users newcomers.
I can make a PR

playground: show warnings

Deploy Production build

Currently the development build is published.

Broken html in guide/ocaml/#variants

Translation infra

Not sure what we should do here. High pri, as many translations are coming in.

Missing words in `External` Guide

The last sentence of this section https://reasonml.github.io/guide/language/external is missing some words.

Some small "bugs"

Hi !
The new ReasonML's website is really cool, but I have point some little bugs :

• https://reasonml.github.io/guide/tools the pictures are dead
• https://reasonml.github.io/guide/ocaml in the OCaml part, there are some anoying \ in the code

document bundler for bs

FAQ Question: What is the recommended standard+/core library (or libraries)?

I suppose we don't have much of an answer yet, but the question keeps coming up regardless

Translation to other languages

Option to try new syntax in playground

I realise the new proposed syntax #1299 is a bit of a minefield, but would it be possible to have an option on the Try page to explicitly select the WIP (with appropriate warnings, 'beta' status, summary of differences/changes, code-snippets showing real-life examples/advantages, etc) branch.

I would like to try it for myself before jumping to conclusions and the only way right now seems to download the repo, switch branch and use rtop/refmt or build and run the website locally. This may also help with testing, as people try to (a) understand and explore and (b) think up pathological case and (c) convince people of benefits.

"Try Reason" generated javascript bleeds into program output in Firefox

First screenshot is Firefox 54 on Linux. Second is Chromium 60 on Linux.

Try Reason page should have several examples to try out/start from

CodeMirror lint integration

I tried to get the CodeMirror lint plugin working with the online playground.

Seems doable. So I wanted to ask if you like the idea and if I should proceed and finalize the proof of concept.

New playground fails to compile code that is incorrectly pretty-printed, when it would normally work fine

OCaml's pprintast has some bugs (among other flaws). One of those bugs is that # operators will be printed incorrectly. E.g.

let f thing => thing##x

will be printed as

let f thing = ## thing x

And because the playground compiles the pretty-printed OCaml instead of using the AST from refmt directly, it will fail to compile. When refmt is used normally as part of the build process however, it uses the AST instead and will compile correctly.

Try Reason: Javascript execution error is displayed in OCaml pane, and clears JavaScript pane

If there is an error in execution of the generated JavaScript, the error will be displayed in the OCaml pane. Additionally, the JavaScript pane will be cleared, so you'll have no idea what even caused the error! 😀

Put companies section at the bottom of front page instead

icon overlaps quickstart link on mobile

maybe just hide the icon at mobile sizes?

Try Reason: Base64 encode URLs

The share URLs are extremely long. It might be a good idea to base64 encode the query param value to make it merely very long. See reason-tools for inspiration.

remove unused code in playground

just like http://bucklescript.github.io/bucklescript/js-demo/ does

For the playground we should just take https://github.com/BuckleScript/bucklescript-playground

Upload source file into Playground.

It will be nice to be able to upload a source file and extract it's code into the playground. My initial thoughts are we add a custom right-click menu by attaching it's event listener to the playground textarea(reason). Something like this jsfiddle.

Right-clicking on a relative link triggers navigation

Steps to reproduce

Right-click on a link on reasonml.github.io that points to somewhere else on reasonml.github.io.

Expected behavior

I would be able to view the context menu for the link without navigation

What actually happens

My browser navigates to the link I right-click on.

Additional information

This doesn't appear to happen on other sites using Gatsby (e.g., Segment's blog, https://www.gatsbyjs.org/).

I'm using Firefox 56 on Linux.