A refined tool for exploring open-source projects on GitHub with a file tree, rich Markdown and image previews, multi-pane multi-tab layouts and first-class support for Ink syntax highlighting.

Overview

Ink codebase browser, "Kin" 🔍

The Ink codebase browser is a tool to explore open-source code on GitHub, especially my side projects written in the Ink programming language. It offers multi-pane, multi-tab interfaces for looking at source code from projects on GitHub, and generates Markdown previews and syntax highlighting for many languages including Ink.

The Ink codebase browser running in the browser on a browser window and on an iPhone

The codebase browser is a full-stack Ink application. It's written in pure Ink except for the syntax highlighting library used to highlight non-Ink source code (highlight.js) and Torus used as the UI rendering backend. In addition to these libraries, the project leans on September for building the frontend and for syntax highlighting Ink source code; and it depends on Merlot for rendering Markdown file previews.

"Kin" was my codename for the project before I gave it its final name of the Ink codebase browser — I liked the name because it's an anagram of "ink", and it's short.

Features

There are three main problems I wanted to solve with the codebase browser.

  1. Most of my side projects written in Ink are open-source on GitHub, but GitHub doesn't (yet) syntax highlight Ink source code. This makes Ink code harder to read on GitHub than it has to be.
  2. GitHub's file browser interface isn't great for just exploring the file hierarchy of a project. Compared to modern code editors, with a file tree sidebar, multi-pane and multi-tab layouts,
  3. Frequently, I find myself needing to reference Ink source files on my GitHub from elsewhere on the Internet like a blog, and I'm disappointed that I can't simply link to a line-numbered, syntax-highlighted file preview. I wanted some way to embed Ink source files from other webpages.

The codebase browser solves all of these problems through the main interface and the "proxy" service described below. In addition, to improve the experience of looking around a project the app supports some extra features initially unplanned. Some of these are described below.

Ink syntax highlighting

The codebase browser uses September's Ink syntax highlighting algorithm to syntax highlight Ink programs. The algorithm is compiled to JavaScript so it can run fully in the browser.

Ink codebase browser with two panes of Ink source code open

Rich file previews

The codebase browser recognizes four different types of files

  1. Binary "blob" files, which are ignored for the purpose of the file preview
  2. Image files which are displayed as images in the preview
  3. Text files, which are displayed with line numbers and syntax highlighting, if the language can be detected
  4. Markdown files, which are rendered as their compiled versions with Merlot's Markdown engine (note that Merlot isn't fully compliant with any common Markdown spec -- it mostly just has the subset that I use, though it's being improved.)

Ink codebase browser viewing a rendered Markdown file

You can see an example Markdown file preview above, next to an Ink source file that's been syntax highlighted. Below, we have a TypeScript React file next to an image preview.

Ink codebase browser viewing an image preview

File previews require the full file to be fetched from GitHub and potentially parsed locally, so files larger than 1MB are not rendered.

File tree and multi-pane multi-tab layout

As we can see above, Ink codebase browser lets us browse files in a GitHub repository as if we have a text editor or IDE open to the project on a filesystem. Compared to GitHub's browsing interface, where each page can only show one folder and file at a time, this interface with multiple panes and tabs makes it much easier to explore and read source code.

Tabs and panes can't be drag-and-dropped to rearrange them. I'm not sure if I'll bother adding that functionality, to be honest. But for now, all files initially open in the leftmost/topmost pane, and can be moved to other panes with the right arrow (→) button.

Syntax highlighting as a service

The Ink codebase browser has a less obvious second feature, which is what I call syntax highlighting as a service.

I frequently want to show some bit of Ink program online, on one of my technical blogs or linked from a comment or tweet, but simply linking to a file or a GitHub preview is suboptimal because Ink has no syntax highlighting support in most places. Given that this project already had a way to syntax highlight Ink code for the web, I chose to repurpose this code to make a service that acts as an HTTP proxy that highlights any Ink code passing through it.

A demo page showing embedded syntax highlighted Ink source files

Using this "proxy" service, I can embed links to syntax-highlighted versions of Ink source files that live on my GitHub repositories. For example, above is a sample document that takes advantage of this. You can see a live demo at code.dotink.co/demo.

Architecture

The Ink codebase browser is a full-stack Ink application. The backend is written in Ink as a single HTTP monolithic server, serving a few different API routes to interface with GitHub's API and act as the syntax highlighting proxy. The frontend is an Ink application that renders to the DOM using a Torus compatibility layer. I've used this approach a few times now, with other projects like Merlot and the Ink playground.

The backend is a simple HTTP server. In addition to serving static files, it provides a few internal API endpoints that map 1:1 to specific GitHub API endpoints but translate and filter API responses to the specific data needed by the client-side UI.

There are a few different pieces of isomorphic Ink code being used in the codebase browser. Much of the standard library is, obviously, cross-compiled to JavaScript. But the syntax highlighting library from the September compiler toolchain is both compiled to JavaScript and run natively on the backend, and the Markdown engine from Merlot is also compiled down for the browser.

Development

Kin uses a Makefile for development tasks. To develop Kin, you'll need to install Ink and the September compiler. inkfmt is optional, and used for code formatting.

  • make run starts the web server in the same way as the production environment. To run the server, you'll need to replace the dummy token in secrets.sample.ink with your GitHub access token and copy it to secrets.ink.
  • make watch runs make build every time a relevant Ink source file in ./src or ./lib changes.
  • make check or make t runs unit tests, which lives in test/.
  • make fmt runs the inkfmt code formatter over all Ink source code in the project.

Build tasks

Because of the number of dependencies in this project, Kin has a multi-part build process. We first build four different components (three of which change rarely), and bundle them into one production bundle at the end.

  • make build-libs, make build-september and make build-merlot perform builds of different dependencies of Kin -- standard library dependencies, and dependencies from September and Merlot (syntax highlighter and Markdown engine).
  • make build builds the frontend JavaScript bundle from ./src/app.js.ink.
  • make build-all performs a fresh build, assuming all sibling dependencies (September and Merlot) are present next to this project's root directory on your system.

September and Merlot are development-time dependencies for this project, but these libraries are compiled to JavaScript vendored into the project, so for normal builds using just make build, they are not necessary to be on your machine.

You might also like...

⚡ the first open-source redis client made with care and acessibility-first 🚀

⚡ Redis UI The first open-source project to create an awesome and accessible UI for Redis as a native desktop application. ✨ 🦄 🚀 How to develop loca

Dec 5, 2022

A markdown-it plugin that process images through the eleventy-img plugin. Can be used in any projects that uses markdown-it.

markdown-it-eleventy-img A markdown-it plugin that process images through the eleventy-img plugin. Can be used in any projects that use markdown-it. F

Dec 20, 2022

🆙 Upscayl - Free and Open Source AI Image Upscaler for Linux, MacOS and Windows built with Linux-First philosophy.

🆙 Upscayl - Free and Open Source AI Image Upscaler for Linux, MacOS and Windows built with Linux-First philosophy.

v1.3 will come around 12 September Upscayl 🆙 Free and Open Source AI Image Upscaler simplescreenrecorder-2022-08-23_20.17.02.mp4 Upscayl is a cross-p

Jan 9, 2023

🆙 Upscayl - Free and Open Source AI Image Upscaler for Linux, MacOS and Windows built with Linux-First philosophy.

🆙 Upscayl - Free and Open Source AI Image Upscaler for Linux, MacOS and Windows built with Linux-First philosophy.

Upscayl 🆙 Free and Open Source AI Image Upscaler Upsacyl.Demo.mp4 Upscayl is a cross-platform application built with the Linux-first philosophy. This

Sep 21, 2022

The source code for the Discord Previews website.

discordpreviews.com The source code for the Discord Previews website. Setup Development Setup Install dependencies via npm install Use Docker Compose

Oct 26, 2022

Mirror from https://github.com/BochilGaming/games-wabot/tree/multi-device

Games-Wabot Join Group Diskusi NO BOT Deploy to Heroku Heroku Buildpack BuildPack LINK FFMPEG here IMAGEMAGICK here FOR TERMUX USER Type mentioned bel

Dec 20, 2022

An Open-Source Platform to certify open-source projects.

An Open-Source Platform to certify open-source projects.

OC-Frontend This includes the frontend for Open-Certs. 📜 After seeing so many open-source projects being monetized 💵 without giving any recognition

Oct 23, 2022

Small library to create classes without using class syntax.

Clazz.js Small library to create classes without using class syntax. Compatibility For internet explorer 11 or higher. Example script src="Clazz.js"

Dec 25, 2021

A card for Home Assistant Lovelace for exploring the history of your entities interactively and in real time.

A card for Home Assistant Lovelace for exploring the history of your entities interactively and in real time.

History explorer card This is a custom history card for Home Assistant. This card offers a highly interactive and configurable way to view the history

Dec 31, 2022
Comments
  • /bin/sh : september not found

    /bin/sh : september not found

    Hi there, On running the make build a error is raised /bin/sh: 1: september: not found. I am also unable to install the september compiler.

    Regards, BLI-P

    opened by BLI-P 0
Owner
Linus Lee
Languages, interpreters, compilers. Building better tools and workflows, usually on the Web, sometimes for the Web.
Linus Lee
Syntax Highlighter supporting multiple languages, themes, fonts, highlighting from a URL, local file or post text.

Crayon Syntax Highlighter Supports multiple languages, themes, fonts, highlighting from a URL, local file or post text. Written in PHP and jQuery. Cra

Aram Kocharyan 1.1k Nov 26, 2022
Syntax highlighting, like GitHub

Close up of The Starry Night by Vincent van Gogh (1889) with examples of starry-night over it starry-night Syntax highlighting, like what GitHub uses

Titus 585 Dec 21, 2022
Fancytree - JavaScript tree view / tree grid plugin with support for keyboard, inline editing, filtering, checkboxes, drag'n'drop, and lazy loading

Fancytree Fancytree (sequel of DynaTree 1.x) is a JavaScript tree view / tree grid plugin with support for keyboard, inline editing, filtering, checkb

Martin Wendt 2.6k Jan 9, 2023
Open! Inclusive! Collaborative! A community for enthusiasts exploring new technologies, working on innovative ideas and helping each other grow together. Open Issues, Raise ideas, Make Pull Requests!

About Us OplnCo previously known as Devstucom represents Open Inclusive Collaborative. We as a community help our fellow students build skills through

OpInCo Community 4 Oct 13, 2022
Meogic-tab-manager is an extensible, headless JavaScript tab manager framework.

MeogicTabManager English document MeogicTabManager是一个有可拓展性的、headless的JavaScript标签页管理框架。 MeogicTabManager旨在提供可自由组装页面框架、自定义页面组件、甚至覆盖框架自带事件响应的开发体验。 Meogi

meogic-tech 5 Oct 8, 2022
optimize image & upload file to cloud as image bed with tiny image automic.

Rush! 图片压缩 & 直传图床工具 这是一个兴趣使然的项目, 希望 Rush! 能让这个世界的网络资源浪费减少一点点 下载 Downloads 获取最新发行版 功能 Features 拖拽批量压缩图片, 支持格式 jpg/png/gif Drop to optimize, jpg/png/gif

{ Chao } 3 Nov 12, 2022
Freewall is a cross-browser and responsive jQuery plugin to help you create grid, image and masonry layouts for desktop, mobile, and tablet...

Freewall Freewall is a cross-browser and responsive jQuery plugin to help you create many types of grid layouts: flexible layouts, images layouts, nes

Minh Nguyen 1.9k Dec 27, 2022
An idiomatic way to enforce values not to be null nor undefined, with first-class support for TypeScript

nullthrows An idiomatic way to enforce values not to be null or undefined, with first-class support for TypeScript. Very lightweight with no dependenc

Expo 4 Jul 23, 2022
Easily open daily notes and periodic notes in new pane; customize periodic notes background; quick append new line to daily notes.

Obsidian daily notes opener This plugin adds a command for opening daily notes in a new pane (so that a keyboard shortcut could be used!) and gives ex

Xiao Meng 16 Dec 26, 2022
Lit + File Based Routing + Nested Layouts

Lit File Based Routing Lit router for nested layouts and file based routing. Similar to https://remix.run/ but at client side. Demo Package Archived i

Rody Davis 9 Jan 14, 2022