DEV Community: Kushal

Announcing Open Knowledge Compiler: a compiler for the Open Knowledge Format

Kushal — Thu, 06 Aug 2026 13:50:23 +0000

Raw engineering artifacts go in. A living, queryable, agent-readable knowledge base comes out.

TL;DR — Open Knowledge Compiler (open-knowledge-compiler, Apache-2.0) is a new open-source tool that continuously compiles a Git repository — its code, pull requests, and optionally Jira — into a knowledge base that is simultaneously a browsable wiki for humans and a structured, queryable graph for AI agents. The output is a conformant OKF (Open Knowledge Format) bundle, checked by the tool's own conformance validator, not just claimed. This post explains what OKF is, what Knowledge Compiler actually does today, and where the two genuinely different roles — producer and consumer — split apart.

The problem this is solving

If you've tried to wire an AI coding agent into a real codebase, you've hit the same wall from three different directions:

The agent can read code, but it can't tell you why a piece of code exists — which business rule it enforces, which Jira ticket motivated the change, whether it's actually tested.
Documentation about "what this system does" lives in five places — a wiki nobody updates, a Confluence page from eighteen months ago, tribal knowledge in someone's head, and scattered code comments — and none of them are current.
Every new agent, every new tool, every new integration re-solves the same problem: how do I assemble enough context about this codebase to be useful?

This is exactly the gap the Open Knowledge Format (OKF) was designed to close, and exactly the gap Open Knowledge Compiler exists to fill automatically, rather than asking a human to maintain it by hand.

What OKF actually is

Open Knowledge Format is an open specification — not a product, not a vendor SDK — published by Google Cloud's Data Analytics and Data Cloud teams (Sam McVeety and Amir Hormati), building on an idea Andrej Karpathy sketched in an LLM-wiki gist. It formalizes a pattern a lot of people were already converging on independently — Obsidian vaults, AGENTS.md/CLAUDE.md files, "metadata as code" repos — into something interoperable.

The spec (currently v0.2) is deliberately small. An OKF bundle is a directory tree of Markdown files. Each file is a concept — a table, a metric, a component, a business rule, whatever your domain needs — with YAML frontmatter on top:

---
type: Component
title: Billing rules
description: Discount calculation and eligibility checks.
tags: [billing, revenue]
generated:
  by: process:some-producer/1.0
  at: 2026-08-05T14:31:43+00:00
---
# Billing rules

Applies the discount cap and eligibility checks before a claim is saved.

Only one field is universally required: type. Everything else — title, description, resource, tags, the provenance-oriented sources/generated/verified fields, the lifecycle status/stale_after fields — is optional or recommended, not mandated. Two filenames are reserved with exact structure: index.md (a directory listing, no general frontmatter) and log.md (a date-grouped, prose changelog, also no frontmatter). Everything else about the file's shape is designed to be tolerant: unknown types, broken links, missing optional fields — none of it is grounds for a consumer to reject a bundle.

That minimalism is the point. OKF's own design principles state it plainly: producers and consumers are independent. Anyone can write a producer (something that emits OKF bundles) or a consumer (something that reads them — a viewer, a search index, an agent) without coordinating with anyone else, as long as both sides honor the spec.

Google shipped a reference producer alongside the spec: an agent that walks BigQuery datasets and drafts OKF concept documents for each table, plus a static HTML bundle visualizer. Both are useful demonstrations. Neither is aimed at software engineering repositories, and neither continuously re-syncs — they're one-shot generation tools.

That's the gap Open Knowledge Compiler fills.

What Open Knowledge Compiler is

Open Knowledge Compiler (package name open-knowledge-compiler, CLI command kc) is an independent, third-party producer for the OKF ecosystem — not affiliated with Google, not part of the OKF spec repository. It has one job: take a software repository's raw artifacts and continuously compile them into an OKF-conformant knowledge base that stays in sync as the repository changes.

The "compiler" framing is deliberate and precise, not marketing. A compiler is a piece of software with a defined input grammar, a deterministic pass over that input, and a reproducible output — not a one-shot LLM summarization job you re-run and hope produces something similar to last time. Open Knowledge Compiler treats knowledge extraction the same way a real compiler treats source code: parse what you can deterministically, treat inference (the LLM layer) as an optional enrichment pass on top, and never let inference decide identity.

Six stages, always in this order: Collect (Git, PRs, optionally Jira) → Extract (deterministic parsing, then an optional LLM pass) → Normalize (turn raw facts into stable, identified entities) → Diff (compute what changed) → Persist (one atomic transaction into Postgres) → Emit (render the OKF wiki bundle from whatever's now in the database).

The database is the durable source of truth. The OKF bundle is a render of it — disposable, regenerated wholesale on every compile, never hand-edited. If a page in the wiki is wrong, the fix is in the compiler or the source data, not the Markdown file.

What's actually implemented today

This is the section where I'd rather under-claim than over-claim. Here's a plain accounting of what exists and runs, versus what's designed-for but not yet built.

The deterministic core (works with zero LLM, zero API keys)

Language analysis: Python and TypeScript, parsed via tree-sitter running in-process — no Node.js runtime required. This produces component, api, and test_coverage entities directly from AST structure: modules, symbols, HTTP routes and their handlers, which tests cover which code.
Git and PR history: a Git collector plus a forge (GitHub) collector that associates pull requests with the entities their diffs touch — via the forge API, not commit parentage, because squash/rebase merges rewrite history and would otherwise silently break this.
Stable identity across recompiles: this is the unglamorous, hardest-to-get-right piece. Every entity gets a slug — component/billing-rules, api/get-discount — and that slug has to survive a second, third, hundredth recompile without churning, or every downstream link, every agent query, every wiki cross-reference breaks on every run. Deterministic entities get natural keys (a component's slug comes from its file path and symbol structure). LLM-derived entities go through a match-then-mint cascade — try to match an existing entity by external key, then anchor overlap, then name similarity, and only mint a new slug if nothing matches. The LLM never assigns identity; identity is decided by deterministic rules that happen to consult LLM output.
An append-only delta log: every compile records exactly what was added, changed, removed, or moved, in one atomic transaction. "What changed in this repo in the last week" is a database query, not a diff of Markdown files.

The optional semantic layer (opt-in, requires an LLM provider)

LLM-derived entities: feature, business_rule, and risk — things no AST can see, because they're about intent, not structure. "This function exists because refunds must be capped at 20% of order value" is a business rule; tree-sitter cannot extract that, an LLM reading the code and its context can.
Four provider integrations: Anthropic, OpenAI, Azure OpenAI, and Cloudflare Workers AI, behind one thin interface — so swapping providers is a config change, not a rewrite.
A content-addressed cache: every LLM call is cached by a hash of (prompt template version, model, input content). Re-running a compile on unchanged files costs nothing — the cache serves the prior answer, byte-identical, which is also what keeps entity identity stable across runs. This is the mechanism that makes "recompile the whole repo cheaply" true rather than aspirational.
A Jira collector: opt-in, fetches issues linked from a merged PR's title or body, mints jira_story entities and links them to the PRs that closed them.

Retrieval and the MCP server

Hybrid search: PostgreSQL full-text search always available; optional embeddings (pgvector) fused with keyword results via reciprocal rank fusion when enabled. No embeddings configured? Search still works, keyword-only — retrieval degrades gracefully, it doesn't fail.
A read-only MCP server (kc serve) — this is the part that turns the OKF bundle from something an agent reads into something an agent queries. It exposes:

Tool	What it answers
`search_knowledge`	Hybrid keyword + semantic search over everything compiled
`get_entity`	Full detail for one entity: payload, source anchors, relationships, provenance
`impact_plan`	"If I change this, what else in the repo is affected?"
`resolve_dependency`	Resolves an import/package coordinate to another compiled repo
`list_entities`	Every entity of a given type
`recent_changes`	What changed in the last N compiles
`which_pr_introduced`	Which PR (or the bootstrap compile) first added this entity
`coverage_for`	Which tests cover this component
`knowledge_stats`	Entity counts, last compile metadata
`test_plan`	Concrete coverage gaps for a component, as targets an agent could act on

The server never compiles anything — it's read-only, always. Compilation is a separate, CI-triggered step. This matters for the same reason a database's read replica and its write path are usually different concerns: you don't want an agent's queries able to mutate the knowledge base it's querying.

OKF conformance — checked, not assumed

This is the piece I want to be most transparent about, because it's also the most interesting story from actually building this.

The wiki emitter was originally built against an early draft of the OKF spec. While writing this announcement and researching the spec's actual GitHub repository directly, it became clear the authoritative spec had already moved to v0.2 — with real, breaking changes from that earlier draft (a timestamp field renamed to a generated: {by, at} object; provenance moved from a body-text # Citations section into a sources frontmatter array; stricter rules for the two reserved filenames).

That discovery surfaced actual bugs — not stylistic drift, real conformance failures: the wiki's index.md was emitting frontmatter fields the spec explicitly forbids there; a sources key was colliding in name (but not shape) with the spec's own provenance vocabulary. Those got fixed. Two things came out of fixing them:

kc validate-okf — a command that checks an emitted bundle against the actual conformance rules (parseable frontmatter, a non-empty type field, reserved-filename structure) rather than assuming the emitter got it right.
kc compile --emit-only — because a spec-version bump only ever needs to change how already-compiled knowledge is rendered, this re-runs just the Emit stage against the database, with no new compile, no re-parsing, no LLM calls. Rolling out a spec update across every repo you've compiled is cheap by construction, not something you re-pay full compile cost for.

Every compile run now records which OKF version its wiki targeted (okf_spec_version), the same way it already tracked its own fact and entity schema versions. This is recorded in ADR-013, one of thirteen architectural decision records that document why the system is built the way it is, not just what it does.

Honest nuance: conformance here means the required and recommended fields (type, title, description, resource, tags) plus the correctly-shaped generated provenance block. The newer optional OKF v0.2 families — verified trust tiers, status/stale_after lifecycle fields, the Attested Computation concept type for verifiable, executable knowledge — are not populated by Knowledge Compiler today. They're real, interesting extension points; they're future work, not shipped features.

Where the producer/consumer split actually matters

OKF's own design insists producers and consumers stay independent, and this is worth taking seriously rather than treating as a spec footnote — it's the reason this tool is useful to people who will never install it.

Anyone can point a generic OKF viewer, a search indexer, or a completely different agent framework at a bundle Open Knowledge Compiler produced, without installing Knowledge Compiler or touching its database. Conversely, Knowledge Compiler's compiled Postgres database is genuinely useful (via kc serve's MCP tools) even to someone who's never heard of OKF — the OKF bundle is one output of the system, not the whole point of it.

For humans, and for agents — genuinely different experiences of the same knowledge

For a human, the output is a wiki. Push the knowledge/wiki branch (the reference publisher target — the destination is pluggable, GitHub Pages and Confluence publishers are additive, not built yet) and GitHub renders it as ordinary Markdown pages, cross-linked, with an index.md you can click through. No special tooling to read it. That's the whole point of choosing "just Markdown, just files" as the substrate.

For an agent, there are two genuinely different ways in, and it's worth being precise about which one you're using:

Read the OKF bundle directly — any agent, any tool, zero KC-specific integration. It's Markdown with YAML frontmatter; every modern coding agent already knows how to read that.
Query the MCP server — this is richer than reading files, because it's not just retrieval, it's structured traversal of a graph: "what does changing this component affect," "resolve this import to the repo it actually lives in," "what covers this with tests." That's a live query over the compiled database, not a grep over rendered Markdown.

Neither path requires the other. An agent that only speaks "read files" still gets a synchronized, provenance-carrying knowledge base. An agent that speaks MCP gets the graph underneath the Markdown.

Real numbers, not hypotheticals

Knowledge Compiler has been dogfooded on real, private codebases — one primary service repository, one library it depends on, and on its own source tree. These are actual compiled states as of this writing, not illustrative examples:

Repository	Entities	Relationships	Notes
Primary service repo	3,016	4,555	105 APIs, 51 business rules, 554 features, 263 risks extracted with the LLM layer enabled
A library it depends on	967	1,413	Compiled separately, linked via cross-repo dependency resolution
Open Knowledge Compiler (itself)	458	880	Compiled with `--no-llm` — deterministic entities only

That third row is worth pausing on: the tool compiles itself. kc verify — a zero-write shadow compile that checks the incrementally-maintained state against a full recompile — reports the compiled state of Open Knowledge Compiler's own repository as equivalent to a fresh full compile. kc validate-okf reports the resulting bundle as fully conformant against OKF v0.2. Self-hosting a compiler on its own source is a real, verifiable claim, not a metaphor.

The cross-repo case is a real scenario worth spelling out, because it's the one that comes up constantly in any codebase with more than one repository: Repo A depends on a library, Repo B. Compile both into the same database, add one line to Repo A's config mapping the import prefix to Repo B's registered name, and resolve_dependency will resolve some_lib.SomeClass to the actual compiled entity in Repo B — its payload, its relationships, its provenance — without Repo A's compile ever reading across the repository boundary at compile time. This is deliberately a query-time-only mechanism (ADR-011) — no shared schema changes, no cross-repository writes, nothing that risks one repo's compile depending on another's compile order.

What this is not (yet)

Being specific about the boundary matters more than the feature list, so here it is plainly:

Not a plugin ecosystem — yet. The architecture is designed around pluggable stages (collectors, extractors, LLM providers, retrieval strategies, publishers), discovered via standard Python packaging entry points and activated only by explicit configuration — never by merely being installed, which is the property that keeps compilation reproducible. Today, the built-in plugins (the Python/TypeScript analyzers, the Git and Jira collectors, the four LLM providers) are wired directly rather than through that discovery mechanism; the entry-point activation path is designed but not yet the live path. Third-party plugins aren't a real, working story yet.
Not proven at large scale. The architecture targets repositories up to roughly 5 million lines of code. The actual dogfood evidence above is on repositories in the hundreds to low thousands of compiled entities. That's real, verifiable evidence at the scale it exists at — it is not evidence of behavior at 5M LOC.
No version-pinned or release-aware queries. "What changed in this dependency between the version I'm pinned to and the latest" is not answerable today. It's an explicitly deferred design item, not a bug.
No database-less mode. Every compile requires PostgreSQL. There's an explicit, written-down design exploration for a lighter-weight mode that would trade away cross-run identity stability and the delta log for zero infrastructure — but it's a parked brainstorm document, not a roadmap commitment.
Not affiliated with Google or the OKF spec authors. This is an independent, third-party implementation targeting a spec Google published and continues to evolve. If OKF changes again — and its own versioning policy says it will — Knowledge Compiler has to track that, the same ongoing-maintenance category of cost it already accepts for tree-sitter grammars and LLM provider APIs changing underneath it.

Trying it

git clone https://github.com/kushal-omnius/open-knowledge-compiler.git
cd open-knowledge-compiler
python -m venv venv && venv\Scripts\activate   # or source venv/bin/activate
pip install -e .[all]
docker compose up -d                            # Postgres + pgvector

# Point it at any local git repo
kc init --slug my-service --forge-ref github.com/you/my-service --dir /path/to/repo
kc compile --full --no-llm --dir /path/to/repo  # deterministic pass, no API keys needed
kc inspect --dir /path/to/repo                  # see what got compiled
kc validate-okf --dir /path/to/repo             # confirm the emitted bundle is OKF-conformant

No API keys, no LLM provider, no embeddings configuration required to see real output. Enabling the semantic layer ([llm] enabled = true in the generated kc.toml) and embeddings ([embeddings] enabled = true) are both later, opt-in steps, each independently toggleable.

The direction this is heading — clearly marked as direction, not done

Everything above this line is real and running. Everything in this section is where the project is aimed, and none of it should be read as already built:

A real plugin ecosystem, once the built-in plugins have proven the interfaces stable enough to hand to third parties — the current wiring is deliberately the simple path until that trigger fires, not a permanent decision.
Version-aware queries across compiled repositories — "what changed in this dependency between the two versions I care about" — as a thin layer over the existing delta log rather than a new storage mechanism.
Additional OKF v0.2 field families — trust tiers, staleness lifecycle, and eventually mapping something like mutation-kill-rate data onto the Attested Computation concept type, so a business rule's compiled entity could carry a verifiable, re-runnable check rather than just a description.
The long-term evaluation question: whether knowledge compiled this way measurably improves what AI agents produce when working in a codebase — code changes, generated tests, answers to engineering questions — compared to an agent with no compiled context at all. That's the actual north star. Everything described in this post is the infrastructure a fair test of that question requires; it is not, itself, evidence that the test has been run or won.

Closing

Open Knowledge Format gives the ecosystem a shared, minimal answer to "what should a knowledge file look like." Open Knowledge Compiler answers a narrower, harder question underneath that: for a living software repository, where does that file's content come from, and how does it stay true as the code keeps changing?

The answer here is: deterministically wherever possible, an LLM only where structure genuinely can't reach, identity that survives recompilation, provenance on every fact, and a conformance checker that verifies the output rather than trusting the emitter. That's a compiler, in the actual sense of the word — and it's now open source, Apache-2.0, and running on real code today.

Repository: github.com/kushal-omnius/open-knowledge-compiler
License: Apache-2.0
Spec it targets: OKF v0.2

Contributions, issues, and honest skepticism are all welcome — see CONTRIBUTING.md in the repo.

Diffey.in: The Online Text Comparison & Diff Tool

Kushal — Sat, 15 Nov 2025 14:13:25 +0000

Introducing Diffey: The Effortless Online Text Comparison & Diff Tool

Have you ever found yourself struggling to spot the differences between two versions of a document, a piece of code, or even a simple block of text? Whether you’re a developer reviewing code, a writer editing drafts, or a student checking assignments, comparing text can be tedious and error-prone.

That’s why I built Diffey — Free Online Text Comparison and Diff Tool — a free, privacy-friendly online diff tool designed to make text comparison fast, accurate, and enjoyable.

Why Diffey?

There are plenty of diff-tools out there, but I wanted something that was

Instant: No sign-up, no installation, just open and compare.
Flexible: Works for code, documents, essays, or any text.
Privacy-first: Your data never leaves your browser.
User-friendly: Clean interface, easy to use, and accessible from any device.

Key Features

Side-by-side Comparison: Paste your texts into two editors and see differences highlighted in real time.
Granular Control: Choose to compare by line, word, or character for the level of detail you need.
Handy Tools: Swap, clear, and copy text with a single click.
Character Count: Instantly see the length of each version.
Theme Toggle: Switch between light and dark modes for comfortable viewing.
No Cost, No Catch: 100% free, with no ads or tracking.

Who Is Diffey For?

Developers: Review code changes, debug, or check merge conflicts.
Writers & Editors: Track revisions, compare drafts, or check for accidental changes.
Students & Teachers: Spot similarities or differences in assignments and essays.
Anyone: If you need to compare text, Diffey is for you!

How to Use Diffey

Visit diffey.in
Paste your two text versions into the “Version A” and “Version B” editors.
Click “Compare” — differences are instantly highlighted.
Adjust the diff granularity as needed, swap or clear text, and enjoy a distraction-free experience.

Final Thoughts

I created Diffey to solve my own frustrations with clunky, privacy-invasive diff tools. My hope is that it helps you work faster and with more confidence, whether you’re coding, writing, or just curious about what’s changed.

Give it a try and let me know what you think! Your feedback and suggestions are always welcome.

Happy comparing!
https://diffey.in

Also check out GivenWhenZen — Online Gherkin Editor and Formatter by Diffey.in

Originally published at https://www.kushalbhalaik.xyz on November 15, 2025.

GivenWhenZen - A Free Online Gherkin Editor for BDD Enthusiasts by Diffey.in

Kushal — Fri, 24 Oct 2025 16:28:27 +0000

Hello, folks!!

I come bearing news: I finally completed something that I wanted to work on for a long time: GivenWhenZen-A Free Online Gherkin Editor/Formatter for BDD Enthusiasts.

🎯 Why I Built This:

As a QA developer deeply involved in BDD (Behavior-Driven Development), I often found myself switching between different tools to format and validate Gherkin feature files. Though there are a few options available, BUT I wanted something simpler-a clean, fast, browser-based editor/validator that just works. I vibe-coded it in a few hours, drawing inspiration from JSONlint.com.

✨ Key Features:

• Real-time formatting with smart indentation
• Instant validation and linting
• Support for Cucumber, JBehave, and SpecFlow
• Dark/Light theme options
• Keyboard shortcuts for productivity
• Zero setup required-works in your browser

💡 Built to inspire:

• Clean, minimalist UI inspired by modern code editors
• Fast performance with instant feedback
• Built using vanilla JavaScript for maximum performance
• free to use

• BDD practiti
oners (anyone who used BDD in 2025)
• QA engineers
• Product owners writing acceptance criteria
• Developers implementing Cucumber/SpecFlow tests

🔗 Try it out: https://diffey.in/givenwhenzen

Also try out the Diffey.in - Text Comparison & Diff Tool Diffey.in - Text Comparison & Diff Tool

Getting started with Deno

Kushal — Sat, 15 Feb 2020 14:09:25 +0000

In this article, I’m going to show you how to get started with Deno — A secure runtime for JavaScript and TypeScript. We’ll see Installation of Deno, Hello World program and setting up an http-server.

The What?

Deno is a secure runtime for Javascript & Typescript (right out of the box) just like Nodejs is a runtime for Javascript. Deno was created by same guy who created Nodejs i.e. Ryan Dahl.

Deno aims to improve what Ryan Dahl thinks he should’ve done with Nodejs like:

Installing Deno.

There are few options available on official site deno.land/.

We are gonna install it using Power-shell command:

`iwr https://deno.land/x/install/install.ps1 -useb | iex`

The Deno.exe executable file is stored in C:\Users<username>.deno\bin\deno.exe by default.

In macOS or Linux $HOME/.local/bin

Following command will give info about Deno, V8 Engine & Typescript version installed on your machine.

`deno --version`

Hello World — Writing first program with Deno.

Open up your terminal and just type following:

`deno [https://deno.land/std/examples/welcome.ts](https://deno.land/std/examples/welcome.ts)`

will result into:

What happened here is we execute a code present in a remote file, AWESOME!!

Now let’s execute a local code:

Create a file inside “C:\deno” > index.ts (it could have .js extension for a javascript file)

Now using terminal execute following command:

`deno index.ts`

`or`

`deno index.js`

Setting up an http-server.

Deno provides an http-server i.e.

`[https://deno.land/std@v0.30.0/http/server.ts](https://deno.land/std@v0.30.0/http/server.ts)`

As provided on official website example, here’s how you can create a running server on your machine:

Code:

`import { serve } from "https://deno.land/std@v0.30.0/http/server.ts";`

`const s = serve({ port: 5000 });`

`console.log("Listening on http://localhost:5000/");`

`for await (const req of s) {
  req.respond({ body: "Hello World!!" });
}`

just copy paste above code into your “index.ts” file and run it with following command.

`deno -A index.ts`

-A flag provides all the necessary permission for your app to run on your machine

Using Oak middle-ware with deno http server.

Oak is a middleware framework for Deno’s net server, more on this can be found on GitHub repo: https://github.com/oakserver/oak

NOW let’s create a GET & POST endpoint by altering our “index.ts” code with following:

import { Application, Router } from "[https://deno.land/x/oak/mod.ts](https://deno.land/x/oak/mod.ts)";

const router = new Router();

router.get("/", context => {
  context.response.body = "Hello World!";
});

router.post("/", context => {
  context.response.body = "You have made a POST request!";
});

const app = new Application();

app.use(router.routes());
app.use(router.allowedMethods());

const server = app.listen({ port: 5000 });

console.log("Listening on [http://localhost:5000/](http://localhost:5000/)");

Result:

So, that was it regarding installing Deno, writing first ‘Hello-World” program and setting up an http-server along with Oak middleware.

Resources:
Deno — a better Node.js? | Krzysztof Piechowicz : https://www.youtube.com/watch?v=mzfw9TwBiQc&t=616s

Deno Examples: https://deno.land/#example

Oak Middleware: https://github.com/oakserver/oak

Original article on: https://blog.kushalbhalaik.xyz/getting-started-with-deno/

GitHub Pages — A Comprehensive guide w/ images (Part 2)

Kushal — Sun, 12 Jan 2020 07:00:28 +0000

This is part 2 of the article series GitHub Pages — A Comprehensive guide w/ images

Recently I started building my personal website as everyone is building one for themselves these days. I got a cool TLD (.xyz), and that is the only money I wanted to spend. Since then I’ve been looking for ways to host it without any costs.

In part 1 of this series we saw how to publish GitHub User Pages and how to link it with custom-domain.In this article we’ll see how to have more than one Github Pages per account (Yes, it is possible). Commençons!!

Before proceeding make sure you already have a repository .github.io

Setting up Multiple Github Pages:

Let’s create a new repository:

Goto Github.new and fill out the new repository details, I’ll call it demo:

Note: It is important to keep this repository public

Now goto repository settings:

On Settings page, scroll down to Github Pages section:

Make the repository Public, if you see following message:

Once repository is Public GitHub Pages will become enabled for the current repository

Click on None, then view current options:
we can either choose following options:
Using “master” branch of demo repository for publishing GitHub pages (Like in GitHub User Pages)
Using /docs page under “master” branch for publishing GitHub Pages
We’ll be using gh-pages branch option which is currently not available as gh-pages branch doesn’t exist for demo repository as of yet

Copy the demo repository link:

Now clone the repo to local machine: Here, far11ven is my GitHub username

~$ git clone https://github.com/far11ven/demo.git

Create local gh-pages branch and push it to GitHub:

~$ cd demo
~$ git branch gh-pages
~$ git push remote -u origin gh-pages

Go back to demo settings on GitHub and select gh-pages as source for publishing:

After this step whatever you put in gh-pages branch will be automatically published.

Let’s create a simple index.html file within this repository:

~$ echo “Hello gh-pages!!” > index.html

Add, commit and push your changes to GithHub remote:

~$ git add *
~$ git commit -m “Initial commit”
~$ git push -u origin gh-pages

You can see in your browser demo repository has been published

You will have a main GitHub User Page (One per account) username.github.io and all other repos will be published as sub pages

or,

if you have already linked a custom-domain to your GitHub User Page, the n you can see the published page at www.example.com/your-repo-name
in my case demo repo will be published at far11ven.github.io/demo

Setting up custom-domains:

i) Setting up Github Pages as a domain

To have our subpages be listed as demo page we need to do following changes in our GitHub repo and our Domain provider

Create a CNAME file in your repository: I will be doing it via GitHub UI, just create a CNAME file (with no extension) and just enter your sub-domain name inside it, nothing else. in my case, I want to make demo pages appear as your-website.com

Once Done, commit your changes.

Add a new DNS record on your DNS provider: We need to change existing CNAME records to point to created GitHub pages i.e. username.github.io

ii) Setting up Github Pages as a sub-domain:

To have our subpages be listed as demo page we need to do following changes in our GitHub repo and our Domain provider

Create or Edit an existing CNAME file in your repository: I will be doing it via GitHub UI, in my case, there is already a CNAME File so I ‘ll just edit the existing file and replace everything in it with my sub-domain, nothing else. in my case, I want to make demo pages appear as demo.kushalbhalaik.xyz

Once Done, commit your changes.

Add a new DNS record on your DNS provider for existing Domain: We need to change existing CNAME records to point to created GitHub pages i.e. username.github.io

Important Points:

Again, at this point, nothing needs to be done from our end, we need to wait for changes to reflect on both GitHub and Cloudflare end, Which may take some time (usually its prompt) but may take some time based on your DNS provider
You won’t be able to access your pages via username.github.io, or username.github.io/our-repoin case you try and enter this in browser, you’ll be redirected to your custom domain or custom sub-domain
Your can-not add multiple GitHub Pages as a sub-doman to GitHub User Page i.e demo.far11ven.github.io in my case is not a valid url

Final Result:

We have successfully created a sub-domain to host our another github-page, follow these steps to create even more pages within your website.

Cheers!!

Original article on: https://blog.kushalbhalaik.xyz/github-pages-a-comprehensive-guide-w-images-part-2/

GitHub Pages — A Comprehensive guide w/ images (Part 1)

Kushal — Sat, 11 Jan 2020 16:45:56 +0000

Recently I started building my personal website as everyone is building for themselves these days. I got a cool TLD (.xyz), and that I is the only money I wanted to spend. Since then I’ve been looking for ways to host it without any costs.

I’ve tried different host providers such as Heroku, 000webhost so far, which are good options. My website is vastly static pages so far until I figure out how to have a cms such as Ghost to be integrated with Gatsby for adding content periodically (Of course for free). Anyways I thought if my site is mostly static pages so why not give Github Pages a try (it’s been on my list for a quite sometime now) and along the way I encountered various hurdles and there wasn’t an elaborate article around it. So folks here we are :)

This is part 1 of this article series, part 2 will be coming soon. Enchanté.

Setting up Github Pages:

This is the most straight forward thing, it’s all neatly illustrated here on Github Pages, but as this article‘s name suggests I’m bound:

We’ll start by creating a repository on Github:

Goto Github.new, a cooler way to create Github repositories (You’ll see).

Make sure your repo-name is username.github.io
The pages ending with username.github.io are called User Pages, where username could belong to an individual or an organization

Note: It is important to make your repository Public, in order for your GitHub User pages to be accessible to all

We won’t be creating any other branch, because User Pages require to be built from master branch.
And in this article, we won’t use Jekyll to publish our pages.

First clone the repo to local machine: Here, username is GitHub username

~$ git clone https://github.com/username/username.github.io.git

Create an index.html file inside this repository:

~$ cd **username**.github.io

~$ echo “Hello World!!” > index.html

Add, commit and push your changes to Github remote:

~$ git add *

~$ git commit -m “Initial commit”

~$ git push -u origin master

Type {username.github.io} in browser and you’re done publishing your first website to github pages.

Setting up Github Pages on your custom-domain:

We have successfully created and deployed Github Pages. But I want users to visit my custom domain kushalbhalaik.xyz. Lets link’em up:

Created a CNAME file in your repository: I will be doing it via GitHub UI, just create a CNAME file (with no extension) and just enter your domain name inside it, nothing else.

Once Done, commit your changes.

Change DNS records on your DNS provider: We need to change existing CNAME records to point to created github pages i.e. username.github.io

Important Points:

At this point, nothing needs to be done from our end, we need to wait for changes to reflect on both GitHub and Cloudflare end, Which may take some time (usually its prompt) but may take some time based on your DNS provider
You won’t be able to access your pages via username.github.io, in case you try and enter this in browser, you’ll be redirected to your custom domain

So this was all to get you started with your very own Github Pages (User). In Part 2 of this series we’ll be taking deeper look into gh-pages and linking pages to your sub-domain. Stay Tuned!!

Original article on: https://blog.kushalbhalaik.xyz/github-pages-a-comprehensive-guide-w-images-part-1/

Bootstrap icons — Overview

Kushal — Fri, 03 Jan 2020 05:42:26 +0000

#bootstrap #html

Bootstrap is a large and complex frontend library which we all fancy having some powerful functionality and customization built-in. Occasionally though, when you need to have icons in your web projects; you go straight to Font-awesome or Glyphicons (Bootstrap v3). But developers and designers often felt constricted to the fact that they have to rely on some other third party library for the icons having to pay for icons they desire. This just didn’t seem right for any of us.

Fast forward 2019, gone are the days when we had to choose between Font-awesome or Glyphicons (Bootstrap v3), For the first time ever, Bootstrap has its own icon library, custom designed and built for its components… (navbars, button, cards, and more).

You can Track latest releases on Github here, also you can checkout Bootstrap icons documentation.

Getting Started

With npm

`npm install bootstrap-icons`

Download

Download the project from here, and from the icons folder and directly copy icons SVGs which you require in your project.

Usage

Choose how you would like to integrate Bootstrap icons in your web application.

External image

Use directly from the project directory and reference them like normal images with the <img> element.

Code:

`<img src="/assets/img/bootstrap.svg" width="64" height="64" title="Bootstrap">`

Preview:

Embedded

Embed your icons within the HTML of your page (as opposed to an external image file). Here we’ve used a custom width and height.

Code:

`<svg class="bi bi-chevron-right" width="64" height="64" viewBox="0 0 20 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
      <path fill-rule="evenodd" d="M6.646 3.646a.5.5 0 01.708 0l6 6a.5.5 0 010 .708l-6 6a.5.5 0 01-.708-.708L12.293 10 6.646 4.354a.5.5 0 010-.708z" clip-rule="evenodd"/>
</svg>`

Preview:

As CSS

You can also use the SVG within your CSS (be sure to escape any characters, such as # to %23 when specifying hex color values). When no dimensions are specified via width and height on the <svg>, the icon will fill the available space.

Code:

`               .bi::before {
                              display: inline-block;
                              content: "";
                              background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path fill='none' stroke='%23333' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M5 14l6-6-6-6'/></svg>");
                              background-repeat: no-repeat;
                              background-size: 1rem 1rem;
                            }`

Preview:

Styling

Color can be changed by setting a .text-* class or custom CSS:

Using bootstrap css classes

Code:

`<svg class="bi bi-alert-triangle text-danger" width="64" height="64" viewBox="0 0 20 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg">`

`                              ...`

`</svg>`

Preview:

Using custom css classes

Code:

`.my-custom-css-class{
                      color:green;
                    }`

Preview:

Using Style Attribute

Code:

`style="color:blue;"`

Preview:

Original article on: https://blog.kushalbhalaik.xyz/bootstrap-icons-overview/

Email Templating with EJS (Node + Express + SendGrid)

Kushal — Thu, 02 Jan 2020 06:54:18 +0000

nodejs #express #ejs

I’ve been building a social links website 8link, which requires me to interact with my users at different levels. So the type of email interaction with my users, I’ve narrowed it down to the following categories of emails:

Welcome email (With verify link)
Password reset link
Automated response to user queries
The actual response to User queries
Occasional promo or newsletters

I’ve been using a Node.js +Express back-end and I wanted to achieve it with same frame-work. So I started using SendGrid Email API to achieve this goal.

SendGrid already has a Templating service, if you are interested you can check it here.

Back to Templating with EJS,
in This article, we’ll see how can we create Re-Usable HTML Templates with EJS and then deliver them with SendGrid.

We’ll start by creating a simple node project:

npm init sendgrid-mailer

Install following dependencies,

npm i --save express cors ejs

Our Package.json should look like:

Let’s create a simple endpoint to serve our email “/hello”

Notice //set express view engine to ejs
app.set(“view engine”, “ejs”);

it should give us the following response:

We are halfway there, Now create a welcome-mail.ejs file in views (Template) folder in the project root directory.

Now add some HTML code in there, which will serve as an underlying template for our welcome mail:

You will see the following syntax in this HTML, which is used to receive data before rendering it. We are using the following variables for manipulating data:

//these are EJS expressions to dynamically receive and display data while rendering an HTML

<%= user_firstname %>
<%= confirm_link %>

Now we need to make changes to our “/hello” endpoint

We’ll need to import following to our index.js file:

//imports
const path = require(“path”);
const ejs = require(“ejs”);

and our “/hello” app route function will change to :

app.get(“/hello”, (*req*, *res*, *next*) => {
let emailTemplate;
let capitalizedFirstName = “John”;
let userEmail = “John@example.com”;

ejs
.renderFile(path.join(__dirname, “views/welcome-mail.ejs”),
{
  user_firstname: capitalizedFirstName,
  confirm_link: “http://www.8link.in/confirm=" + userEmail
})
.then(*result* => {
  emailTemplate = result;
  res.send(emailTemplate);
})
.catch(*err* => {
  res.status(400).json({
      message: “Error Rendering emailTemplate”,
      error: err
     });
  });

});

in here, ejs.renderFile() take .ejs file path and specify values for _user_firstname _and confirm_link

Now if we hit “/hello” we get:

Whoops.. we now have our welcome template, we just have to deliver it via email now.

Let's integrate SendGrid now:

First signup for SendGrid mail API, by clicking here and get the API -KEY

Now get @sendgrid/mail package from npm.

npm i --save @sendgrid/mail

Import following into index.js

const SGmail = require(“@sendgrid/mail”);

Now in our code first register the SendGrid API Key

SGmail.setApiKey(process.env.SendGrid_Key);

//Note: store SendGrid_Key in your projects' config file

and replace **res.send(emailTemplate); **with following code:

const message = {
  to: userEmail,
  from: { email: “welcome@8link.in”, name: “8link” },
  subject: “Welcome link”,
  html: emailTemplate
};

return SGmail.send(message).then(*sent* => {

// Awesome Logic to check if mail was sent

   res.status(200).json({
      message: “Welcome mail was sent”

      });

}).catch(*err* => {

      console.log(“Error sending mail”, err);
      res.status(400).json({
          message: “Welcome mail was not sent”,
          error: err
      });

});

Our final code should look like:

And if I hit my “/hello” endpoint again, I should see that mail was sent successfully:

Full Code on Github: https://github.com/far11ven/SendGrid-Mailer

Original article on: https://blog.kushalbhalaik.xyz/email-templating-with-ejs-node-express-sendgrid/