Lobsters: JanetDocs

ayushnix

Unrelated but please consider switching the syntax highlighting theme to something different which is accessible. The defn keyword on the home page is barely readable and fails WCAG AA and APCA.

Maybe it’s just me but no syntax highlighting feels better than most syntax highlighting themes out there.

toastal

Additionally better would be to do syntax highlighting at build time or served with the HTML already lexed/parse/classed… as a JavaScript allowlister, I don’t see any color on my end & these code examples are all just static content. The “playground” section needs dynamic, realtime highlighting but the rest doesn’t which would be better for users experience too.
veqq
How is it now? It’s a work in progress and I’ll happily take any recommendations you have; I’m no designer.

@toastal I agree. My personal site does it at build time, but there are many knowledge gaps and architectural blockers. I have two general ideas:
- build example bodies into html with inline css to directly from the DB
- fork Joy and add static generation/memoization to usefully target static code blocks
I’d like to deyakshave this. The lsp has done the hard work already. I could also use @ianthehenry ’s “playground”.
- ayushnix
  
  Significantly better than before (with an Lc value of 75.9 between #363636 and #D8D8F0 in light mode), thanks!
  
  The modus themes by Protesilaos Stavrou comes to mind when one wants to choose an accessible color scheme so if that’s an option, maybe you can consider that.
- toastal
  
  build example bodies into html with inline css to directly from the DB
  
  I would have assumed this would have been possible if not some sort of cache like Varnish without digging too far into it.
phoebos

Janet Docs is a great resource to build on the rather terse official documentation/API.

What did you change? (It took me a while to notice janetdocs.org != janetdocs.com, with the content looking the same)
- veqq
  The original had not been updated in about 4 years. So this:
  
  updated core bindings (and the playground) by 20 versions
  
  fixed many broken pages e.g. this now works
  
  added library coverage (now over 50 libraries and 3000 bindings)
  
  upstreamed an ace mode-janet (for playground syntax highlighting)
  
  misc. colors changes (mostly to dark mode and especially to the playground) for legibility (work in progress)
  
  added an importer
  
  My next goals:
  
  make a tutorial (for beginners, even to programming) (and with a method based on old language textbooks)
  
  fix the playground’s format button
  
  surface bindings (core and other packages) better
  - Vaelatern
    
    I assume of course you’ve seen https://janet.guide ?
    
    veqq
    
    It displays Janet’s superpowers but doesn’t explain how to do basic tasks and cover core functions like has-value? or put-in. Currently, Janet relies on people already knowing Lisp. A few friends have struggled as a result (and I’ve personally implemented many basic functions 1:1 because I couldn’t figure out what they were name.) I want to address this.
    
    phoebos
    
    Exactly my experience too. Compare to the outstanding Fennel documentation: both a tutorial and a reference which are easy to read, easy to search, and not generated from docstrings.