diff --git a/.github/pages/index.html b/.github/pages/index.html deleted file mode 100644 index 73709ba6..00000000 --- a/.github/pages/index.html +++ /dev/null @@ -1 +0,0 @@ -Testing diff --git a/.github/website/backup/ideas.md b/.github/website/backup/ideas.md new file mode 100644 index 00000000..e69de29b diff --git a/.github/website/backup/index2.html b/.github/website/backup/index2.html new file mode 100644 index 00000000..799cafa9 --- /dev/null +++ b/.github/website/backup/index2.html @@ -0,0 +1,189 @@ + + + + + + Hacker Laws + + + + + + + + + + + +
+

Hacker Laws

+

Laws, Theories, Principles and Patterns that developers will find useful.

+
+ + +
+ +
+

Introduction

+

There are lots of laws which people discuss when talking about development. This repository is a reference and overview of some of the most common ones. Please share and submit PRs!

+

Note: This repo contains an explanation of some laws, principles and patterns, but does not advocate for any of them. Whether they should be applied will always be a matter of debate, and greatly dependent on what you are working on.

+ + + + + +
+ ↑ Top + +
+
+ + +
+

90–9–1 Principle (1% Rule)

+

The 90-9-1 principle suggests that within an internet community such as a wiki, 90% of participants only consume content, 9% edit or modify content and 1% of participants add content.

+

Real-world examples:

+ +

See Also: Pareto Principle

+ + + + + +
+ ↑ Top +
+
+ + +
+

90–90 Rule

+

The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time.

+

This is a wry reinterpretation of the Pareto Principle (or 80-20 rule) that highlights the real-world challenges of completing engineering work. This sentiment is also echoed in Hofstadter's Law.

+ + + + + +
+ ↑ Top +
+
+ + +
+ + + + + + + + + + diff --git a/.github/website/backup/index3.html b/.github/website/backup/index3.html new file mode 100644 index 00000000..52f90800 --- /dev/null +++ b/.github/website/backup/index3.html @@ -0,0 +1,194 @@ + + + + + + Hacker Laws + + + + + + + + + + + + + +
+

Hacker Laws

+

Laws, Theories, Principles and Patterns that developers will find useful.

+
+ + +
+ +
+

Introduction

+

There are lots of laws which people discuss when talking about development. This repository is a reference and overview of some of the most common ones. Please share and submit PRs!

+

Note: This repo contains an explanation of some laws, principles and patterns, but does not advocate for any of them. Whether they should be applied will always be a matter of debate, and greatly dependent on what you are working on.

+ + + + + +
+ ↑ Top +
+
+ + +
+

90–9–1 Principle (1% Rule)

+

The 90-9-1 principle suggests that within an internet community such as a wiki, 90% of participants only consume content, 9% edit or modify content and 1% of participants add content.

+

Real-world examples:

+ +

See Also: Pareto Principle

+ + + + + +
+ ↑ Top +
+
+ + +
+

90–90 Rule

+

The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time.

+

This is a wry reinterpretation of the Pareto Principle (or 80-20 rule) that highlights the real-world challenges of completing engineering work. This sentiment is also echoed in Hofstadter's Law.

+ + + + + +
+ ↑ Top +
+
+
+ + + + + + + + + + diff --git a/.github/website/backup/index4.html b/.github/website/backup/index4.html new file mode 100644 index 00000000..e69de29b diff --git a/.github/website/build/.gitignore b/.github/website/build/.gitignore new file mode 100644 index 00000000..72e8ffc0 --- /dev/null +++ b/.github/website/build/.gitignore @@ -0,0 +1 @@ +* diff --git a/.github/website/generate.py b/.github/website/generate.py new file mode 100644 index 00000000..83efac4c --- /dev/null +++ b/.github/website/generate.py @@ -0,0 +1,161 @@ +"""Generate the Hacker Laws website from the Hacker Laws README""" + +import argparse +import os +import shutil +from jinja2 import Environment, FileSystemLoader +import markdown +from bs4 import BeautifulSoup + + +def bisect_text(content: str, bisect_line: str) -> tuple[str, str]: + lines = content.splitlines() + head = [] + tail = [] + found = False + for line in lines: + if found is False and line == bisect_line: + found = True + continue + if found: + tail.append(line) + else: + head.append(line) + + return ("\n".join(head), "\n".join(tail)) + + +def load_template(): + """Load Jinja2 template from the specified directory.""" + env = Environment(loader=FileSystemLoader(TEMPLATE_DIR)) + return env.get_template(TEMPLATE_FILE) + + +def prepare_markdown(path: str) -> str: + """ + Pre-process the README markdown by removing content we will not show in + the final website. + """ + + # Load the markdown content. + with open(path, "r", encoding="utf-8") as f: + content = f.read() + return content + + +def parse_markdown(markdown_content: str): + (_, remains) = bisect_text(markdown_content, "---") + (links, remains) = bisect_text(remains, "---") + (_, content) = bisect_text(remains, "") + + md = markdown.Markdown(extensions=['toc']) + links = md.convert(links) + print(f"links: {links}") + md.convert(content) + toc = md.toc + + markdown_sections = content.split("\n#") # Split by Markdown headings + sections = [] + laws = [] + for markdown_section in markdown_sections: + if markdown_section.strip(): + lines = markdown_section.split("\n", 1) + title = lines[0].strip("# ").strip() + content = md.convert(lines[1] if len(lines) > 1 else "") + full_content = md.convert(markdown_section) + id = title.lower().replace(" ", "-") + laws.append({"title": title, "content": content, "id": id}) + sections.append({ + "title": title, + "content": content, + "id": id, + "full_content": full_content + }) + + return (links, toc, sections) + + +def extract_static_files(html_content, output_dir): + """ + Extract linked CSS, JS, and image files and copy them to the output + directory. + """ + soup = BeautifulSoup(html_content, "html.parser") + files_to_copy = [] + + # Extract stylesheets + for link in soup.find_all("link", href=True): + href = link["href"] + if not href.startswith(("http", "//")): # Ignore external links + files_to_copy.append(href) + + # Extract + + + + + + + + + + + + + +
+

Hacker Laws

+

Laws, Theories, Principles and Patterns that developers will find useful.

+
+ +
+ + {{ links }} +
+ + {{ toc }} +
+ + + {% for section in sections %} +
+ {{ section.full_content | safe }} + + +
+ {% endfor %} + +
+ + + + + + + diff --git a/.github/website/src/script.js b/.github/website/src/script.js new file mode 100644 index 00000000..0dd5292d --- /dev/null +++ b/.github/website/src/script.js @@ -0,0 +1,18 @@ +$(document).ready(function() { + $("h1, h2, h3, h4, h5, h6").each(function() { + var $heading = $(this); + var headingId = $heading.attr("id") || $heading.text().trim().toLowerCase().replace(/\s+/g, "-"); + + // Ensure a unique ID + $heading.attr("id", headingId); + + // Create the anchor link + var $anchor = $('') + .attr("href", "#" + headingId) + .addClass("header-link") + .html("#"); + + // Append to the heading + $heading.append($anchor); + }); +}); diff --git a/.github/website/src/styles.css b/.github/website/src/styles.css new file mode 100644 index 00000000..af2a0227 --- /dev/null +++ b/.github/website/src/styles.css @@ -0,0 +1,73 @@ +html { + scroll-behavior: auto !important; +} + +body { + font-family: 'Inter', sans-serif; + background-color: #fff; + color: #333; + padding-top: 70px; +} +.container { + max-width: 800px; +} +header { + text-align: center; + margin-bottom: 2rem; + padding: 2rem 0; + border-bottom: 1px solid #e5e5e5; +} +h1, h2, h3, h4, h5, h6 { + font-family: 'Libre Baskerville', serif; + /* Avoid scrolling under the sticky header. */ + scroll-margin-top: 80px; +} +.law-section { + margin-bottom: 2rem; + padding: 1.5rem; + background-color: #fff; + border-bottom: 1px solid #e5e5e5; + position: relative; +} +.law-section h2 { + position: relative; + display: flex; + align-items: center; +} +.law-section h2 a.anchor { + text-decoration: none; + color: #999; + margin-left: 0.5rem; + visibility: hidden; +} +.law-section:hover h2 a.anchor { + visibility: visible; +} +.social-sharing a { + margin-right: 0.75rem; + font-size: 1.2rem; + color: #555; + text-decoration: none; +} +.social-sharing a:hover { + color: #000; +} +.back-to-top { + margin-top: 1rem; +} + +/* Initially hide the hash link */ +.header-link { + text-decoration: none; + margin-left: 12px; /* Increased left padding */ + opacity: 0; + transition: opacity 0.2s; + font-size: inherit; /* Matches the heading size */ +} + +/* Only show the hash when the whole section is hovered */ +section:hover .header-link, +article:hover .header-link, +div:hover .header-link { + opacity: 1; +} diff --git a/.github/workflows/build-on-pull-request.yaml b/.github/workflows/build-on-pull-request.yaml index 1b192460..c530184f 100644 --- a/.github/workflows/build-on-pull-request.yaml +++ b/.github/workflows/build-on-pull-request.yaml @@ -1,18 +1,27 @@ -# This pipeline builds the PDF ebook on any pull request to master. -name: "Build PDF" +name: "Validate Pull Request" on: pull_request: - branches: - - master jobs: + test-website-build: + runs-on: ubuntu-24.04 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Test Website Build + run: | + cd .github/website + make install + make build + cp -r build/. '../pages' + ls -al "../pages" + prepare-pdf: - # Focal Fossa. Please don't use 'latest' tags, it's an anti-pattern. - runs-on: ubuntu-20.04 + runs-on: ubuntu-24.04 steps: - # Checkout the code. - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 # Set a descriptive version. For PRs it'll be the short sha. - name: Set Version @@ -41,3 +50,4 @@ jobs: with: name: hacker-laws.md path: hacker-laws.md + diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index a47c581d..c2be014c 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -30,6 +30,13 @@ jobs: uses: actions/checkout@v4 - name: Setup Pages uses: actions/configure-pages@v5 + - name: Build Website + run: | + cd .github/website + make install + make build + cp -r build/. '../pages' + ls -al "../pages" - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/README.md b/README.md index f986f326..2c81bc3a 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ -# 💻📖 hacker-laws +

hacker-laws 💻📖

+

🧠 Laws, Theories, Principles and Patterns that developers will find useful.

-Laws, Theories, Principles and Patterns that developers will find useful. - -[Translations](#translations): [🇮🇩](./translations/id.md) [🇧🇷](./translations/pt-BR.md) [🇨🇳](https://github.com/nusr/hacker-laws-zh) [🇩🇪](./translations/de.md) [🇫🇷](./translations/fr.md) [🇬🇷](./translations/el.md) [🇮🇹](https://github.com/csparpa/hacker-laws-it) [🇱🇻](./translations/lv.md) [🇰🇷](https://github.com/codeanddonuts/hacker-laws-kr) [🇵🇱](./translations/pl.md) [🇷🇺](https://github.com/solarrust/hacker-laws) [🇪🇸](./translations/es-ES.md) [🇹🇷](https://github.com/umutphp/hacker-laws-tr) [🇯🇵](./translations/jp.md) [🇺🇦](./translations/uk.md) [🇻🇳](./translations/vi.md) +--- -Like this project? Please considering [sponsoring me](https://github.com/sponsors/dwmkerr) and the [translators](#translations). Also check out this podcast on [The Changelog - Laws for Hackers to Live By](https://changelog.com/podcast/403) to learn more about the project! You can also [download the latest PDF eBook](https://github.com/dwmkerr/hacker-laws/releases/latest/download/hacker-laws.pdf). Check the [Contributor Guide](./.github/contributing.md) if you are keen to contribute! +- 📖 Check out my new book [Effective Shell](https://effective-shell) +- 🌍 Check out the website [hacker-laws.com](https://hacker-laws.com) +- ☕️ Like this project? Consider [buying me a coffee with a one-off donation](https://github.com/sponsors/dwmkerr?frequency=one-time) +- 🧠 Check out my new project [Terminal AI](https://github.com/terminal-ai) +- 🎧 Try the podcast [The Changelog - Laws for Hackers to Live By](https://changelog.com/podcast/403) +- 📖 Download the [PDF eBook](https://github.com/dwmkerr/hacker-laws/releases/latest/download/hacker-laws.pd) --- @@ -95,8 +99,7 @@ There are lots of laws which people discuss when talking about development. This ## Laws -And here we go! - +Laws can be opinions on inevitabilities in the world of software engineering, or wry observations on unavoidable realities. ### 90–9–1 Principle (1% Rule) diff --git a/assets/site/index.html b/assets/site/index.html new file mode 100644 index 00000000..432939d6 --- /dev/null +++ b/assets/site/index.html @@ -0,0 +1,119 @@ + + + + + Interactive Hacker Laws Stack + + + +
+ + + + + + + diff --git a/assets/site/index2.html b/assets/site/index2.html new file mode 100644 index 00000000..96b6d4ca --- /dev/null +++ b/assets/site/index2.html @@ -0,0 +1,110 @@ + + + + + + Interactive Hacker Laws Stack + + + +
+ + + + + + diff --git a/assets/site/index3.html b/assets/site/index3.html new file mode 100644 index 00000000..88dd4f2d --- /dev/null +++ b/assets/site/index3.html @@ -0,0 +1,127 @@ + + + + + Interactive Hacker Laws Stack + + + +
+
+
+ + + + + + diff --git a/assets/site/index4.html b/assets/site/index4.html new file mode 100644 index 00000000..22627dd5 --- /dev/null +++ b/assets/site/index4.html @@ -0,0 +1,158 @@ + + + + + + + Interactive Hacker Laws Stack + + + +
+
+
+ + + + + +