Linguist

MDX supports several extensions including Math (LaTeX), GitHub Flavored Markdown (GFM) features like autolinks, footnotes, task lists, and tables, as well as GitHub-specific features like gemoji, mentions, and references.

// Math
$$ L = \frac{1}{2} \rho v^2 S C_L $$

// GFM Task List
* [ ] not done
* [x] done

// GFM Table
| Stuff? | stuff! |
| - | - |
| asdasda | https://example.com |

// GitHub Mentions & Gemoji
@username :+1:

On GitHub.com, language analysis is an asynchronous process:

• Trigger: A low-priority background job is enqueued whenever changes are pushed to the default branch of a repository.
• Caching: Results are cached for the lifetime of the repository and are only updated when the repository is updated.
• Latency: Because analysis runs as a low-priority background job, there may be a delay before the language statistics bar reflects recent changes, especially during periods of high GitHub activity.

Linguist allows you to customize language detection, statistics, and syntax highlighting by adding a .gitattributes file to your project. Use standard git-style path matchers to apply specific Linguist attributes to files or directories.

Important Note: When testing with a local installation of Linguist, attributes will not take effect until the .gitattributes file is committed to your repository. Paths are calculated relative to the position of the .gitattributes file.

# Reclassify .rb files as Java
*.rb linguist-language=Java

# Use hyphens instead of spaces in language names
*.glyphs linguist-language=OpenStep-Property-List

# Language names are case-insensitive and support aliases
*.es linguist-language=js
*.es linguist-language=JS
*.es linguist-language=JAVASCRIPT

MDX allows you to combine Markdown with JavaScript features. You can use ECMAScript Modules (ESM) to import components and export constants, use JSX tags to render components directly in your content, and use curly braces {} to embed JavaScript expressions or logic.

import {Chart} from './chart.js'
export const year = 2018

<Chart year={year} color="#fcb32c" />

Two 🍰 is: {Math.PI * 2}

{(function () {
  const guess = Math.random()
  if (guess > 0.66) return <span style={{color: 'tomato'}}>Look at us.</span>
  return <span>Not me.</span>
})()}

Linguist typically excludes documentation files from language statistics. You can manually mark paths as documentation (to exclude them) or unmark them (to include them) using the linguist-documentation attribute.

# Apply override to all files in the directory
project-docs/* linguist-documentation

# Apply override to a specific file
docs/formatter.rb -linguist-documentation

# Apply override to all files and directories in the directory
ano-dir/** linguist-documentation

Linguist requires a recent version of Ruby. It is highly recommended to use a version manager like rbenv, rvm, asdf, or Homebrew rather than the default macOS/Xcode Ruby.

Linguist depends on charlock_holmes (for encoding) and rugged (for libgit2 bindings), which require the following system libraries:

Required Libraries:

• `cmake"
• pkg-config
• ICU
• zlib
• libcurl
• OpenSSL

Installation on macOS (Homebrew):

brew install cmake pkg-config icu4c

Installation on Ubuntu:

sudo apt-get install build-essential cmake pkg-config libicu-dev zlib1g-dev libcurl4-openssl-dev libssl-dev ruby-dev

To prevent third-party libraries from inflating your project's language statistics, use the linguist-vendored attribute to mark paths as vendored (excluded) or un-vendor them (included).

# Apply override to all files in the directory
special-vendored-path/* linguist-vendored

# Apply override to a specific file
jquery.js -linguist-vendored

# Apply override to all files and directories in the directory
ano-dir/** linguist-vendored

Install the Linguist gem using the standard Ruby package manager:

gem install github-linguist

Generated files (like minified JS or compiled CoffeeScript) can be excluded from language statistics and suppressed in diffs using the linguist-generated attribute.

Api.elm linguist-generated

By default, only languages of type programming or markup are included in language statistics. Languages of other types (like data or prose) are not 'detectable' by default.

Use linguist-detectable to include or exclude paths from statistics. Note that the language must still be defined in languages.yml for this to work.

*.kicad_pcb linguist-detectable
*.sch linguist-detectable
tools/export_bom.py -linguist-detectable