Added a scoll padding for references

archetypes/default.md

@@ -1,4 +1,5 @@
 +++
 title = "{{ replace .File.ContentBaseName "-" " " | title }}"
+weight = 999
 draft = true
 +++

assets/css/custom.css

@@ -0,0 +1,3 @@
+html {
+  scroll-padding-top: 5rem;
+}

config/_default/menu.toml

@@ -6,7 +6,7 @@
 [[main]]
   name = "🚧 ISA Documentation"
   weight = 2
-  pageRef = "#"
+  pageRef = "/isa-docs"
 
 [[main]]
   name = "🚧 Software Documentation"

content/_index.md

@@ -31,7 +31,7 @@ layout = "wide"
 </div>
 
 {{< hextra/hero-button    text="🚧 Learn"                  link="#"         style="margin: calc(var(--hx-spacing)*2)" >}}
-{{< hero-button-secondary text="🚧 ISA Documentation"      link="#" style="margin: calc(var(--hx-spacing)*2)" >}}
+{{< hero-button-secondary text="🚧 ISA Documentation"      link="/isa-docs" style="margin: calc(var(--hx-spacing)*2)" >}}
 {{< hero-button-secondary text="🚧 Software Documentation" link="#"         style="margin: calc(var(--hx-spacing)*2)" >}}
 
 <div class="hx:mb-12">&nbsp;</div>

content/isa-docs/_index.md

@@ -0,0 +1,139 @@
++++
+title = "ISA Documentation"
+
+breadcrumbs = false
+cascade.type = "docs"
++++
+
+The best way to understand a CPU is to take one apart. The Little Computer
+family was designed with exactly that in mind: every detail is intentional,
+every constraint has a reason. The three canonical architectures (LC-2, LC-3,
+and LC-3b) were built to be studied, not just used, and their internal structure
+reflects that philosophy at every level.
+
+At the core, all three share the same foundation. The address bus is 16 bits
+wide, giving a linear address space of 65,536 locations, no segmentation, no
+paging, no virtual memory. Each architecture uses eight general-purpose
+registers (R0-R7), a program counter (PC), and a 3-bit condition code register
+(CC) that tracks the sign of the last result written to a register: negative,
+zero, or positive. Every instruction is exactly 16 bits wide, with the top 4
+bits reserved for the opcode, a constraint that shapes the design of every
+instruction in the set.
+
+Each successive version refines this foundation rather than replacing it. LC-2
+and LC-3 pair the 16-bit address bus with a 16-bit data bus, meaning each memory
+location holds a full 16-bit word - 128 KiB of addressable memory in total.
+LC-3b narrows the data bus to 8 bits: memory locations hold a single byte,
+halving the addressable memory to 64 KiB and introducing byte-level memory
+operations absent in the other two. LC-3 and LC-3b also add privilege levels - a
+distinction between user mode and supervisor mode - which the original LC-2 does
+not have.
+
+What none of them have is equally telling: no flags register, no status
+register, no variable-length instructions, no complex addressing hierarchies.
+The simplicity is not a limitation, it is the point.
+
+Beyond the canonical three, two other architectures are documented here. LC-1
+predates LC-2 and represents the earliest iteration of the family: simpler, more
+constrained, and rarely discussed today. LC-3.2 sits at the other end: an
+unofficial extension that expands the address space to 32 bits and reduces the
+word size to 8 bits, bringing the family closer to the real-world architectures
+it was never meant to replicate.
+
+
+
+## How the Family Evolved
+
+{{% steps %}}
+
+### LC-1
+
+The starting point of the family. An accumulator-based architecture with a
+single register, a 13-bit address space, and just 8 instructions. Extremely
+minimal by design. Closer to a teaching toy than a real CPU.
+
+### LC-2
+
+LC-2 marks the transition from a single-accumulator model to a proper register
+file. The initial revision introduced 4 registers and N,Z condition codes. This
+is a first step away from the extreme minimalism of LC-1.
+
+The final revision settled on 8 registers (R0-R7) and three condition codes (N,
+Z, P), the blueprint that all subsequent canonical architectures would inherit.
+The result is an architecture that feels closer to early 8-bit CPUs like the
+Intel 8080: still simple, but no longer a toy.
+
+### LC-3
+
+The most widely known architecture in the family. The initial revision
+introduced a stack that grows toward zero, PC-relative offsets using sign
+extension instead of zero extension, and register-relative addressing with
+signed offsets.
+
+The revised version added privileged memory, available in two models: fixed and
+selectable. LC-3 has been adopted by numerous universities as the basis for
+introductory computer architecture courses.
+
+### LC-3b
+
+A variant of LC-3 with an 8-bit data bus instead of 16-bit, halving the
+addressable memory to 64 KiB but introducing byte-level memory operations.
+
+Working at the byte level makes LC-3b the closest of the canonical architectures
+to how real-world CPUs actually handle memory.
+
+### LC-3.2
+
+An unofficial extension, not created by Patt and Patel, that expands the address
+bus to 32 bits and narrows the data bus to 8 bits - the same combination used by
+early x86 processors. It is the only architecture in the family that bridges the
+gap between the LC teaching model and real-world CPU design, which is what makes
+it worth studying.
+
+{{% /steps %}}
+
+
+
+## At a Glance
+
+| ISA    | Data Bus Width | Address Bus Width | Memory  | Registers                          | Instruction Width         | Privilege Levels | Status      |
+|:------:|:--------------:|:-----------------:|:-------:|:----------------------------------:|:-------------------------:|:----------------:|:-----------:|
+| LC-1   | 16-bit         | **13-bit**        | 16 kiB  | **One 16-bit accumulator**         | 16-bit (**3-bit** opcode) | No               | **Legacy**  |
+| LC-2   | 16-bit         | 16-bit            | 128 kiB | Eight 16-bit registers (R0-R7)     | 16-bit (4-bit opcode)     | No               | Canonical   |
+| LC-3   | 16-bit         | 16-bit            | 128 kiB | Eight 16-bit registers (R0-R7)     | 16-bit (4-bit opcode)     | Yes (2)          | Canonical   |
+| LC-3b  | **8-bit**      | 16-bit            | 64 kiB  | Eight 16-bit registers (R0-R7)     | 16-bit (4-bit opcode)     | Yes (2)          | Canonical   |
+| LC-3.2 | **8-bit**      | **32-bit**        | 4 GiB   | **Eight 32-bit registers** (R0-R7) | 16-bit (4-bit opcode)     | Yes (2)          | **Variant** |
+
+
+
+## A Note on Sources
+
+All data in this section is sourced from primary references: the original books,
+course materials, and official publications by Patt and Patel. Every claim is
+cited. If you spot an error or know of a better source, contributions are
+[welcome via GitHub](https://github.com/little-emulator/docs/issues).
+
+
+
+## Explore the Architectures
+
+Each architecture in the family has its own dedicated reference page,
+documenting the instruction set, registers, memory model, and encoding in full
+detail.
+
+### Core Architectures
+
+<br>
+{{< hextra/feature-grid cols="2" >}}
+  {{< hextra/feature-card title="LC-2"  icon="chip" link="lc-2" >}}
+  {{< hextra/feature-card title="LC-3"  icon="chip" link="lc-3" >}}
+  {{< hextra/feature-card title="LC-3b" icon="chip" link="lc-3b" >}}
+{{< /hextra/feature-grid >}}
+
+### Beyond the Canon
+
+<br>
+{{< hextra/feature-grid cols="2" >}}
+  {{< hextra/feature-card title="LC-1"   icon="bookmark" link="lc-1"   subtitle="**Legacy**: The accumulator-based predecessor" >}}
+  {{< hextra/feature-card title="LC-3.2" icon="cube"     link="lc-3.2" subtitle="**Variant**: An unofficial 32-bit extension" >}}
+{{< /hextra/feature-grid >}}

content/isa-docs/lc-1/_index.md

@@ -0,0 +1,5 @@
++++
+title = "Legacy: LC-1"
+weight = 400
+draft = true
++++

content/isa-docs/lc-2/_index.md

@@ -0,0 +1,5 @@
++++
+title = "LC-2"
+weight = 100
+draft = true
++++

content/isa-docs/lc-3.2/_index.md

@@ -0,0 +1,5 @@
++++
+title = "Variant: LC-3.2"
+weight = 500
+draft = true
++++

content/isa-docs/lc-3/_index.md

@@ -0,0 +1,5 @@
++++
+title = "LC-3"
+weight = 200
+draft = true
++++

content/isa-docs/lc-3b/_index.md

@@ -0,0 +1,5 @@
++++
+title = "LC-3b"
+weight = 300
+draft = true
++++

layouts/partials/cite-book.html

@@ -0,0 +1,24 @@
+{{- $author          := .author -}}
+{{- $chapter         := .chapter -}}
+{{- $title           := .title -}}
+{{- $editor          := .editor -}}
+{{- $edition         := .edition -}}
+{{- $publisher       := .publisher -}}
+{{- $year            := .year -}}
+{{- $page            := .page -}}
+{{- $pageEnd         := .pageEnd -}}
+{{- $isbn            := .isbn -}}
+{{- $url             := .url -}}
+{{- $urlArchived     := .urlArchived -}}
+{{- $urlArchivedDate := .urlArchivedDate -}}
+
+{{- if $author }}{{ $author }}, {{ end -}}
+{{- if $chapter }}"{{ $chapter }}" in {{ end -}}
+{{- if $title }}<em>{{ $title }}</em>{{ end -}}
+{{- if $editor }}, ed. {{ $editor }}{{ end -}}
+{{- if $edition }}, {{ $edition }} {{ if $editor }}edn.{{ else }}ed.{{ end }}{{ end -}}
+{{- if or $publisher $year }} ({{ $publisher }}{{ if and $publisher $year }}, {{ end }}{{ $year }}){{ end -}}
+{{- if $page }}, {{ if $pageEnd }}pp. {{ $page }}-{{ $pageEnd }}{{ else }}p. {{ $page }}{{ end }}{{ end -}}
+{{- if $isbn }}. <a href="https://en.wikipedia.org/wiki/Special:BookSources/{{ $isbn }}" target="_blank">ISBN {{ $isbn }}</a>{{ end -}}
+{{- if $url }}. <a href="{{ $url }}" target="_blank">Link</a>{{ end -}}
+{{- if $urlArchived }} (<a href="{{ $urlArchived }}" target="_blank">Archived{{ with $urlArchivedDate }} on {{ . }}{{ end }}</a>){{ end -}}

layouts/shortcodes/cite-book.html

@@ -0,0 +1,52 @@
+{{- /*
+cite-book - Chicago Notes style book citation shortcode.
+Renders a fully formatted Chicago Notes citation for a book, with optional
+chapter, editor, edition, publisher, page range, ISBN (linked to Wikipedia
+BookSources), original URL, and archived URL. All fields are optional except
+author and title.
+
+@param {string} author             Author(s) in "Lastname, Firstname" format.
+@param {string} chapter            Chapter title, if citing a specific chapter.
+@param {string} title              Book title (rendered in italics).
+@param {string} editor             Editor(s) of the volume, if applicable.
+@param {string} edition            Edition (e.g. "3rd", "2nd").
+@param {string} publisher          Publisher name.
+@param {string} year               Publication year.
+@param {string} page               Page number (single) or start of range.
+@param {string} page-end           End of page range (if citing multiple pages).
+@param {string} isbn               ISBN (linked to Wikipedia BookSources).
+@param {string} url                Original URL of the resource.
+@param {string} url-archived       Archived version URL (e.g. Wayback Machine).
+@param {string} url-archived-date  Date of archival (e.g. "2024-01-15").
+
+@example {{< cite-book
+  author="Patt, Yale N. and Patel, Sanjay J."
+  chapter="Appendix A: The LC-2 ISA"
+  title="Introduction to Computing Systems: from Bits and Gates to C and Beyond"
+  edition="1st"
+  publisher="McGraw-Hill"
+  year="2001"
+  page="429"
+  page-end="449"
+  isbn="978-0072376906"
+  url="http://www.mhhe.com/patt"
+  url-archived="https://web.archive.org/web/20170615060857/http://www.mhhe.com/engcs/compsci/patt/"
+  url-archived-date="June 15, 2017"
+>}}
+*/ -}}
+
+{{ partial "cite-book.html" (dict
+  "author"           (.Get "author")
+  "chapter"          (.Get "chapter")
+  "title"            (.Get "title")
+  "editor"           (.Get "editor")
+  "edition"          (.Get "edition")
+  "publisher"        (.Get "publisher")
+  "year"             (.Get "year")
+  "page"             (.Get "page")
+  "pageEnd"          (.Get "page-end")
+  "isbn"             (.Get "isbn")
+  "url"              (.Get "url")
+  "urlArchived"      (.Get "url-archived")
+  "urlArchivedDate"  (.Get "url-archived-date")
+) }}

layouts/shortcodes/cite-ics.html

@@ -0,0 +1,73 @@
+{{- /*
+cite-ics - Shortcode for citing Introduction to Computing Systems by Patt & Patel.
+Pre-fills author, title, publisher, year, ISBN, and URLs based on the edition.
+
+@param {string} edition   Edition of the book ("1", "2", or "3").
+@param {string} chapter   Chapter title.
+@param {string} page      Page number (single) or start of range.
+@param {string} page-end  End of page range (if citing multiple pages).
+
+@example {{< cite-ics edition="1" chapter="Appendix A: The LC-2 ISA" page="429" page-end="449" >}}
+*/ -}}
+
+{{- $edition := .Get "edition" -}}
+{{- $chapter := .Get "chapter" -}}
+{{- $page    := .Get "page" -}}
+{{- $pageEnd := .Get "page-end" -}}
+
+{{- $author    := "Patt, Yale N. and Patel, Sanjay J." -}}
+{{- $publisher := "McGraw-Hill" -}}
+
+{{- $editionString   := "" -}}
+{{- $title           := "" -}}
+{{- $year            := "" -}}
+{{- $isbn            := "" -}}
+{{- $url             := "" -}}
+{{- $urlArchived     := "" -}}
+{{- $urlArchivedDate := "" -}}
+
+{{- if eq $edition "1" -}}
+  {{- $editionString   = "1st" -}}
+
+  {{- $title           = "Introduction to Computing Systems: from Bits and Gates to C and Beyond" -}}
+  {{- $year            = "2001" -}}
+  {{- $isbn            = "978-0072376906" -}}
+  {{- $url             = "http://www.mhhe.com/patt" -}}
+  {{- $urlArchived     = "https://web.archive.org/web/20170615060857/http://www.mhhe.com/engcs/compsci/patt/" -}}
+  {{- $urlArchivedDate = "June 15, 2017" -}}
+{{- else if eq $edition "2" -}}
+  {{- $editionString   = "2nd" -}}
+
+  {{- /* https://icourse.club/uploads/files/647434676ec33b68392bf82c3a014751e8e2345a.pdf */ -}}
+
+  {{- $title           = "Introduction to Computing Systems: from Bits and Gates to C and Beyond" -}}
+  {{- $year            = "2004" -}}
+  {{- $isbn            = "978-0071245012" -}}
+  {{- $url             = "http://www.mhhe.com/patt2" -}}
+{{- else if eq $edition "3" -}}
+  {{- $editionString   = "3rd" -}}
+
+  {{- /* https://icourse.club/uploads/files/96a2b94d4be48285f2605d843a1e6db37da9a944.pdf */ -}}
+
+  {{- $title           = "Introduction to Computing Systems: from Bits and Gates to C/C++ and Beyond" -}}
+  {{- $year            = "2020" -}}
+  {{- $isbn            = "978-1260150537" -}}
+  {{- $url             = "http://www.mhhe.com/patt3" -}}
+{{- else -}}
+  {{ errorf "cite-ics: edition must be 1, 2, or 3, got '%s'" $edition }}
+{{- end -}}
+
+{{ partial "cite-book.html" (dict
+  "author"          $author
+  "title"           $title
+  "chapter"         $chapter
+  "edition"         $editionString
+  "publisher"       $publisher
+  "year"            $year
+  "page"            $page
+  "pageEnd"         $pageEnd
+  "isbn"            $isbn
+  "url"             $url
+  "urlArchived"     $urlArchived
+  "urlArchivedDate" $urlArchivedDate
+) }}

layouts/shortcodes/cite-talk.html

@@ -0,0 +1,59 @@
+{{- /*
+cite-talk - Chicago Notes style conference presentation citation shortcode.
+Renders a fully formatted Chicago Notes citation for a conference talk,
+keynote, poster, or similar presentation.
+
+@param {string} author             Author(s) in "Lastname, Firstname" format.
+@param {string} title              Presentation title (rendered in quotes).
+@param {string} type               Type of presentation (e.g. "Keynote", "Paper", "Poster", "PowerPoint").
+@param {string} event              Conference or event name.
+@param {string} location           City and state/country of the event.
+@param {string} date               Date or month/year of the event.
+@param {string} url                URL of the resource (required if online).
+@param {string} format             File format, if applicable (e.g. "PDF", "PowerPoint").
+@param {string} accessed           Date the resource was accessed.
+@param {string} url-archived       Archived version URL (e.g. Wayback Machine).
+@param {string} url-archived-date  Date of archival (e.g. "June 15, 2017").
+
+@example {{< cite-talk
+  author="Patt, Yale N."
+  title="LC-3, x86, or MIPS: The First ISA for Students to Study"
+  type="Keynote"
+  event="Workshop on Computer Architecture Education"
+  location="San Diego, CA"
+  date="June 9, 2007"
+  url="https://www.csc2.ncsu.edu/faculty/efg/wcae/ISCA2007/FinalProgram.html"
+  format="PowerPoint presentation"
+  accessed="June 8, 2026"
+  url-archived="https://web.archive.org/web/20250129103001/https://www.csc2.ncsu.edu/faculty/efg/wcae/ISCA2007/FinalProgram.html"
+  url-archived-date="January 29, 2025"
+>}}
+*/ -}}
+
+{{- $author          := .Get "author" -}}
+{{- $title           := .Get "title" -}}
+{{- $type            := .Get "type" -}}
+{{- $event           := .Get "event" -}}
+{{- $location        := .Get "location" -}}
+{{- $date            := .Get "date" -}}
+{{- $url             := .Get "url" -}}
+{{- $format          := .Get "format" -}}
+{{- $accessed        := .Get "accessed" -}}
+{{- $urlArchived     := .Get "url-archived" -}}
+{{- $urlArchivedDate := .Get "url-archived-date" -}}
+
+{{- if $author }}{{ $author }}. {{ end -}}
+{{- if $title }}"{{ $title }}"{{ end -}}
+{{- if or $type $event $location $date }} (
+  {{- $type }}
+  {{- if and $type $event }} presentation at {{ end }}
+  {{- if and (not $type) $event }}Presentation at {{ end }}
+  {{- $event }}
+  {{- if and $event $location }}, {{ end }}
+  {{- $location }}
+  {{- if and (or $event $location) $date }}, {{ end }}
+  {{- $date }}).
+{{- end -}}
+{{- if $url }} <a href="{{ $url }}" target="_blank">{{ $url }}</a>{{ with $format }} ({{ . }}){{ end }}.{{ end -}}
+{{- if $accessed }} Accessed {{ $accessed }}.{{ end -}}
+{{- if $urlArchived }} (<a href="{{ $urlArchived }}" target="_blank">Archived{{ with $urlArchivedDate }} on {{ . }}{{ end }}</a>){{ end -}}

layouts/shortcodes/cite-web.html

@@ -0,0 +1,46 @@
+{{- /*
+cite-web - Chicago Notes style web citation shortcode.
+Renders a fully formatted Chicago Notes citation for a web resource, with
+optional author, site name, publication date, access date, archived URL and
+archived date. All fields are optional except title and url.
+
+@param {string} author             Author(s) in "Lastname, Firstname" format.
+@param {string} title              Page title (rendered in quotes).
+@param {string} site               Website or organization name.
+@param {string} date               Publication or last updated date.
+@param {string} url                URL of the resource (required).
+@param {string} format             File format of the resource, if applicable (e.g. "PDF", "DOC").
+@param {string} accessed           Date the page was accessed.
+@param {string} url-archived       Archived version URL (e.g. Wayback Machine).
+@param {string} url-archived-date  Date of archival (e.g. "June 15, 2017").
+
+@example {{< cite-web
+  author="Patt, Yale N."
+  title="The LC-3b ISA"
+  site="University of Texas"
+  date="May 22, 2021"
+  url="https://users.ece.utexas.edu/~patt/21s.460n/handouts/appA.pdf"
+  format="PDF"
+  accessed="May 29, 2026"
+  url-archived="https://web.archive.org/web/20250327170520/https://users.ece.utexas.edu/~patt/21s.460n/handouts/appA.pdf"
+  url-archived-date="March 27, 2025"
+>}}
+*/ -}}
+
+{{- $author          := .Get "author" -}}
+{{- $title           := .Get "title" -}}
+{{- $site            := .Get "site" -}}
+{{- $date            := .Get "date" -}}
+{{- $url             := .Get "url" -}}
+{{- $format          := .Get "format" -}}
+{{- $accessed        := .Get "accessed" -}}
+{{- $urlArchived     := .Get "url-archived" -}}
+{{- $urlArchivedDate := .Get "url-archived-date" -}}
+
+{{- if $author }}{{ $author }}. {{ end -}}
+{{- if $title }}"{{ $title }}."{{ end -}}
+{{- if $site }} {{ $site }}.{{ end -}}
+{{- if $date }} {{ $date }}.{{ end -}}
+{{- if $url }} <a href="{{ $url }}" target="_blank">{{ $url }}</a>{{ with $format }} ({{ . }}){{ end }}.{{ end -}}
+{{- if $accessed }} Accessed {{ $accessed }}.{{ end -}}
+{{- if $urlArchived }} (<a href="{{ $urlArchived }}" target="_blank">Archived{{ with $urlArchivedDate }} on {{ . }}{{ end }}</a>){{ end -}}