Moves rendering to Jekyll

Author: infews

.gitignore

@@ -1,9 +1,5 @@
-<<<<<<< HEAD
-.idea/
-=======
-# ignore lock file of Brew
-# changes all the time
-Brewfile.lock.json
-# ignore build directory of mkdocs
-site
->>>>>>> 3a900c2 (init commit)
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor

.ruby-version

@@ -0,0 +1 @@
+3.3.6

404.html

@@ -0,0 +1,25 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

Brewfile

@@ -17,44 +17,49 @@ Feel free to edit any existing page. We have a _slight_ preference for [referenc
 When adding a new page please keep in mind a few things.
 
 - All files must be valid Markdown syntax and end in the `.md` extension
-- Files in the `/docs` directory will show up in the root
-  - e.g., `/who_is_ora.md` will build a page at `https://alumni-codex.github.io/who_is_ora/`
-- If you want to make a collection of related pages
-  - Create a new directory under `/docs`
-    - e.g., `/docs/pivotal_breakfast/`
-  - Create new pages underneath your new directory and write those pages
-    - `/docs/pivotal_breakfast/ora.md` and `/docs/pivotal_breakfast/gemma.md`; these will render to `https://alumni-codex.github.io/pivotal_breakfast/ora/` and `https://alumni-codex.github.io/pivotal_breakfast/gemma/` respectively
-    - `/docs/pivotal_breakfast/index.md/` will render to `https://alumni-codex.github.io/pivotal_breakfast/`
-
-### Adding New Pages to Nav
-
-Whenever you add new pages, you need to _add them to the left-side navigation __manually___. 
+- Every file needs YAML front matter that looks like this:
+
+```yaml
+---
+title: <My new page title>
+layout: default # so that the side nav renders on this page
+parent: <title of parent page> # puts this page in the side nav
+---
+```
 
-To add these new pages, you need to update the `nav` section of `mkdocs.yml`. Use the existing file as a guide.
+- In order to be connected to the side navigation, the file needs a `parent` (see above)
+  - e.g., `/who_is_ora.md` will build a page at `https://alumni-codex.github.io/who_is_ora/`
+- New Directories are welcome!
+  - The directory needs an `index.md` for this group of related pages 
+  - This `index.md` doesn't need a parent, but it needs a `nav_order: integer` to place it in the Side Nav 
 
 ## Local Development
 
 Please fork the repo for local development. See below re: Pull Requests.
 
-All of the source to this site is in the `main` branch in the `/docs` directory. This directory and its subdirectories adhere to [MkDocs][mkd] patterns.
+All of the source to this site is in the `main` branch directory. This directory and its subdirectories adhere to [Jekyll](https://jekyllrb.com) patterns.
 
 Local development is _not required_, but it can help maintainers get your edits to the web faster.
 
 ### Setup
 To set up a local development environment - that is, to allow for live reload and preview of the built HTML - you will need:
 
-- Homebrew
-- Python 3 + `pip`
+- Homebrew (to install a useful Ruby)
+- Ruby 3.3.x and Bundler
+- 
+## Development
+
+You will need Ruby 3.3.x and Bundler in order to validate locally.
 
 ```bash
-brew bundle # see the Brewfile in the repo root
-pip3 install -r requirements.txt
-mkdocs server
-# make changes to docs (see below)
-# make sure markdown formatted correctly
-deno fmt .
-# make git commit and PR (optional)
+# Install dependencies
+bundle install
+# Run the dev server
+bundle exec jekyll serve
+# Navigate your browser to it
+open http://127.0.0.1:4000/
 ```
+
 ## Submitting a Pull Request
 
 We're using GitHub's PR flow to manage contributions and deal with potential conflicts.

CONTRIBUTING.md

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.0"
+
+group :jekyll_plugins do
+  gem "jekyll-feed"
+  gem "jemoji"
+  gem "just-the-docs"
+end
+
+gem "kramdown-parser-gfm"

Gemfile

@@ -12,25 +12,12 @@ Given that the [Pivotal Alumni Slack][slk] is free, and free Slacks have only 90
 
 - The `main` branch of this repo the source code for this site
 - When changes are made to the `main` brach, GitHub Actions builds and deploys HTML
-- The HTML and CSS are generated with [MkDocs][mkd]
+- The HTML and CSS are generated with [Jekyll](https://jekyllrb.com), the default for GitHub pages
 - This site is hosted via GitHub Pages
 
-## Contributing
+## Development / Contributing
 
 - All changes should come via Pull Request.
 - Please see [CONTRIBUTING.md][contrib] for details on how to add and update files.
 - Be Kind
 - Reach out to Davis - @infews - if you want to help with admin of this site
-
-## Development
-
-You will need Python 3 and the Pip package manager.
-
-```bash
-# Install dependencies
-pip install -r requirements.txt
-# Run the dev server
-mkdocs serve
-# Navigate your browser to it
-open http://127.0.0.1:8000/
-```

README.md

@@ -0,0 +1,120 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+#
+# If you need help with YAML syntax, here are some quick references for you:
+# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
+# https://learnxinyminutes.com/docs/yaml/
+#
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: Pivotal Alumni Codex
+email: [email protected] # maintainer
+description: >- # this means to ignore newlines until "baseurl:"
+  A place for the links to the things we wish we'd taken with us.
+baseurl: "" # the subpath of your site, e.g. /blog
+url: "https://https://alumni-codex.github.io/"
+#twitter_username: jekyllrb
+#github_username:  jekyll
+
+# Build settings
+theme: just-the-docs
+plugins:
+  - jekyll-feed
+
+# Set a path/url to a logo that will be displayed instead of the title
+logo: "/assets/images/just-the-docs.png"
+
+# Set a path/url to a favicon that will be displayed by the browser
+favicon_ico: "/assets/images/favicon.ico"
+
+# Enable or disable the side/mobile menu globally
+# Nav menu can also be selectively enabled or disabled using page variables or the minimal layout
+nav_enabled: true
+
+# Heading anchor links appear on hover over h1-h6 tags in page content
+# allowing users to deep link to a particular heading on a page.
+#
+# Supports true (default) or false
+heading_anchors: true
+
+# Enable or disable the site search
+# Supports true (default) or false
+search_enabled: true
+
+search:
+  # Split pages into sections that can be searched individually
+  # Supports 1 - 6, default: 2
+  heading_level: 2
+  # Maximum amount of previews per search result
+  # Default: 3
+  previews: 3
+  # Maximum amount of words to display before a matched word in the preview
+  # Default: 5
+  preview_words_before: 5
+  # Maximum amount of words to display after a matched word in the preview
+  # Default: 10
+  preview_words_after: 10
+  # Set the search token separator
+  # Default: /[\s\-/]+/
+  # Example: enable support for hyphenated search words
+  tokenizer_separator: /[\s/]+/
+  # Display the relative url in search results
+  # Supports true (default) or false
+  rel_url: true
+  # Enable or disable the search button that appears in the bottom right corner of every page
+  # Supports true or false (default)
+  button: false
+  # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS)
+  focus_shortcut_key: 'k'
+
+# Footer content
+# appears at the bottom of every page's main content
+# Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust markup / liquid-based content.
+footer_content: "Copyright &copy; 2020-2024 by Pivots. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a>"
+
+# Footer last edited timestamp
+last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
+last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
+
+# Footer "Edit this page on GitHub" link text
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "This page on GitHub."
+gh_edit_repository: "https://github.com/alumni-codex/alumni-codex.github.io" # the github URL for your repo
+gh_edit_branch: "main" # the branch that your docs is served from
+# gh_edit_source: docs # the source that your files originate from
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
+
+# Exclude from processing.
+# The following items will not be processed, by default.
+# Any item listed under the `exclude:` key here will be automatically added to
+# the internal "default list".
+#
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+#
+exclude:
+  - .gitignore
+  - .ruby-version
+  - CONTRIBUTING.md
+  - README.md
+#   - .sass-cache/
+#   - .jekyll-cache/
+#   - gemfiles/
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules/
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/

_config.yml

@@ -0,0 +1,3 @@
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="icon" href="/docs/assets/blades.svg"/>

_includes/head_custom.html

@@ -0,0 +1,16 @@
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=IBM+Plex+Sans:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&display=swap');
+
+$body-font-family-pivotal: "IBM Plex Sans", system-ui, -apple-system, blinkmacsystemfont, "Segoe UI", roboto, "Helvetica Neue", arial, sans-serif, "Segoe UI Emoji" !default;
+$mono-font-family-pivotal: "IBM Plex Mono", "SFMono-Regular", menlo, consolas, monospace !default;
+
+body {
+  font-family: $body-font-family-pivotal;
+}
+
+code, .text-mono {
+  font-family: $mono-font-family-pivotal;
+}
+
+h1 {
+  font-weight: 600;
+}

_sass/custom/custom.scss

@@ -1,3 +1,9 @@
+---
+title: Core Practices
+layout: default
+parent: Agile Resources
+---
+
 # Core Practice Discussions
 
 Pivotal engineers would meet periodically over lunch to have a facilitated discussion of one of our core practices — the things we do every day. We made time for these discussions because the "why" of the practices doesn't often get communicated during pair programming, and we wanted to avoid developing "cargo cults" of people who followed the practices dogmatically without understanding their purpose.

_sass/custom/setup.scss

@@ -1,3 +1,9 @@
+---
+title: Facilitation
+parent: Agile Resources
+layout: default
+---
+
 # Facilitation
 
 ## Common Meetings

docs/engineering/core-practice.md renamed to agile-resources/core-practice.md

@@ -0,0 +1,5 @@
+---
+title: Agile Resources
+layout: default
+nav_order: 5
+---

docs/agility-resources/facilitation-notes.md renamed to agile-resources/facilitation-notes.md

@@ -1,3 +1,8 @@
+---
+title: Newsletters of Note
+parent: Agile Resources
+layout: default
+---
 
 # Newsletters of Note
 

agile-resources/index.md

@@ -1,24 +1,34 @@
+---
+title: Practices
+parent: Agile Resources
+layout: default
+nav_order: 1
+---
+
 # Practices
 
+## From Pivotal
 - [Labs Practices](https://labspractices.com/)
     - "Open Sourced" how-to guides from Tanzu Labs, including templates for many sessions
     - Maintained by [Pivot Joe Moore's](mailto:[email protected])
     - Moved to this site when Tanzu consolidated all its learning materials under one banner
-- [The Anchor Playbook](https://tanzu.vmware.com/developer/learningpaths/anchor-playbook/)
+- [The Anchor Playbook](https://tanzu.vmware.com/developer/learningpaths/anchor-playbook/) FIXME
 - [The Pivotal Glossary](https://tanzu.vmware.com/content/blog/the-pivotal-glossary), by Megan Holzer
     - A set of common Pivotal language
 - [Pivotal-style facilitaton notes](facilitation-notes.md)
     - Documenting the basics of how to facilitate a meeting: ground rules, standard meeting agendas, etc.
+- [Tanzu Miro Templates](https://miro.com/miroverse/profile/vmware-pivotal-labs/)
+  - Note: this page might be going away when Tanzu ends their subscription
+
+## Other Sources
+
 - [Atlassian Team Playbooks](https://www.atlassian.com/team-playbook/plays)
     - Another collection of workshops
     - Some overlap with what we used a Pivotal. Many good things here, complete with templates for Atlassian Products
 - [Agile Software Planning: What to do if Classic 2-Week Sprint Planning isn't Working](https://medium.com/@AdamPiel/agile-software-planning-what-to-do-if-classic-2-week-sprint-planning-isnt-working-for-your-team-c482af31a1f8)
-- [Tanzu Miro Templates](https://miro.com/miroverse/profile/vmware-pivotal-labs/)
-    - Note: this page might be going away when Tanzu ends their subscription
 - [Automatic Project Management](http://benchristel.github.io/presentations/pivotal-tracker/#1)
     - A presentation about the Pivotal Tracker Way
 
 ## Team Structure
 
-- Janice Fraser's deck
-  on [Balanced Teams](https://www.slideshare.net/clevergirl/2015-balanced-teams-product-management-engineering)
+- Janice Fraser's deck on [Balanced Teams](https://www.slideshare.net/clevergirl/2015-balanced-teams-product-management-engineering)