Skip to content

Commit 72f4625

Browse files
elopezelopez
authored
Convert to mdbook and fix links (#65)
* Convert to mdBook * Add ToB favicon * Clean up old `docs/` directory * The book is now built and deployed via GitHub Actions * Update contribution instructions with mdBook * Revive links with Wayback Machine * Update http -> https links * Add link and spell checker
1 parent c700f51 commit 72f4625

File tree

106 files changed

+290
-13945
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

106 files changed

+290
-13945
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
name: Deploy GitHub Pages
3+
on:
4+
push:
5+
branches:
6+
- master
7+
workflow_dispatch:
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: read
14+
env:
15+
CARGO_TERM_COLOR: always
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
submodules: true
22+
persist-credentials: false
23+
24+
- name: Install mdbook
25+
run: |
26+
set -euxo pipefail
27+
mkdir mdbook-bin
28+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=mdbook-bin
29+
echo "dd131662665dd91880c8c23d867d36f6a8554286216c3a849b53a27d1a676917 mdbook-bin/mdbook" | sha256sum -c
30+
echo "$PWD/mdbook-bin" >> "$GITHUB_PATH"
31+
32+
- name: Build artifacts
33+
run: |
34+
export MDBOOK_OUTPUT__HTML__GIT_REPOSITORY_URL="https://github.com/$REPO"
35+
export MDBOOK_OUTPUT__HTML__EDIT_URL_TEMPLATE="https://github.com/$REPO/edit/master/{path}"
36+
mdbook build
37+
env:
38+
REPO: "${{ github.repository }}"
39+
40+
- name: Upload artifact
41+
uses: actions/upload-pages-artifact@v3
42+
with:
43+
path: ./docs
44+
45+
deploy:
46+
runs-on: ubuntu-latest
47+
permissions:
48+
pages: write
49+
id-token: write
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
54+
needs: build
55+
steps:
56+
- name: Deploy to GitHub Pages
57+
id: deployment
58+
uses: actions/deploy-pages@v4

‎.github/workflows/markdown.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
name: Check Markdown files correctness
3+
4+
on:
5+
push:
6+
branches:
7+
- master
8+
pull_request:
9+
10+
jobs:
11+
# Extract links from Markdown texts and check if they are alive
12+
markdown-link-check:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- name: Restore lychee cache
17+
uses: actions/cache@v4
18+
with:
19+
path: .lycheecache
20+
key: cache-lychee-${{ github.sha }}
21+
restore-keys: cache-lychee-
22+
- uses: lycheeverse/lychee-action@2b973e86fc7b1f6b36a93795fe2c9c6ae1118621 # for v1.10.0
23+
with:
24+
args: --base . -a 100..=103,200..=299,429 --verbose --no-progress --cache --max-cache-age 1d --scheme http --scheme https './**/*.md'
25+
fail: true
26+
27+
# Spellcheck Markdown files using `retext` and `remark`
28+
# Uses: a custom dictionary file
29+
spellcheck:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v4
33+
- uses: tbroadley/spellchecker-cli-action@v1
34+
with:
35+
# No need to use a dictionary file with the disabled spell plugin
36+
# dictionaries: '.github/workflows/dictionary.txt'
37+
files: "'**/*.md'"
38+
quiet: true
39+
plugins: "indefinite-article repeated-words syntax-mentions syntax-urls"

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
docs/
12
_book/
23
.DS_Store
34
node_modules

‎.lycheeignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
https://vimeo.com/.*
2+
https://web.archive.org/.*
3+
https://.*.reddit.com/.*
4+
https://www.researchgate.net/.*
5+
6+
# behind cloudflare
7+
https://www.cgisecurity.com/.*
8+
9+
# network error from GH
10+
https://csapp.cs.cmu.edu/.*
11+
https://wiki.sei.cmu.edu/.*

‎SUMMARY.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Summary
22

3+
[Introduction](README.md)
4+
35
* [Capture the Flag](intro/README.md)
46
* [Find a CTF](intro/find.md)
57
* [Find a Job](intro/careers.md)
@@ -16,4 +18,6 @@
1618
* [Toolkit Prep](toolkits/prep.md)
1719
* [Operational Tradecraft](tradecraft/README.md)
1820
* [Case Studies](tradecraft/case_studies.md)
19-
* [Contributing](contrib.md)
21+
22+
---
23+
[Contributing](contrib.md)

‎book.json‎

Lines changed: 0 additions & 14 deletions
This file was deleted.

‎book.toml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[book]
2+
title = "CTF Field Guide"
3+
description = "Getting and Using Other People's Computers"
4+
authors = ["Trail of Bits"]
5+
language = "en"
6+
multilingual = false
7+
src = "."
8+
9+
[build]
10+
build-dir = "docs"
11+
12+
[output.html]
13+
google-analytics = "UA-37017099-3"
14+
git-repository-url = "https://github.com/trailofbits/ctf"
15+
edit-url-template = "https://github.com/trailofbits/ctf/edit/master/{path}"
16+
site-url = "/ctf/"

‎contrib.md‎

Lines changed: 15 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,30 +3,26 @@ This book was built on a lot of hard work, most of which happened elsewhere. Wit
33

44
So, reader, when you’ve completed a few CTFs, and you’re ready for more, reach out to this list. They like to support ambition, and they just might know someone who needs some talent.
55

6-
* [Andrew Ruef](http://www.mimisbrunnr.net/~munin/blog/) created the initial proposal and slides
7-
* [Evan Jensen](https://github.com/wontonSlim) developed and refined nearly all of the lessons
6+
* [Andrew Ruef](https://web.archive.org/web/20150219123305/http://www.mimisbrunnr.net:80/~munin/blog/) created the initial proposal and slides
7+
* Evan Jensen developed and refined nearly all of the lessons
88
* [Nick Anderson](https://github.com/PoppySeedPlehzr) ran through the lessons and made numerous improvements
99
* [Alex Sotirov](http://www.phreedom.org/) delivered the ROP lecture and provided feedback
10-
* [Jay Little](https://twitter.com/computerality) reviewed the binary exploitation modules
11-
* [Brandon Edwards](https://twitter.com/drraid) delivered the source auditing lectures and the newspaper app
12-
* [Marcin W](https://twitter.com/marcinw) and [Gotham Digital Science](http://www.gdssecurity.com/) delivered the web security lectures
13-
* [Dino Dai Zovi](http://www.theta44.org/main.html) delivered the introductory exploitation lectures
14-
* [Mike Myers](https://twitter.com/fristle) for contributing the chapter on forensics
10+
* [Jay Little](https://x.com/computerality) reviewed the binary exploitation modules
11+
* [Brandon Edwards](https://x.com/drraid) delivered the source auditing lectures and the newspaper app
12+
* [Marcin W](https://x.com/marcinw) and [Gotham Digital Science](https://www.gdssecurity.com/) delivered the web security lectures
13+
* [Dino Dai Zovi](https://theta44.org/) delivered the introductory exploitation lectures
14+
* [Mike Myers](https://x.com/fristle) for contributing the chapter on forensics
1515

16-
If you're interested in taking a course like this one for credit, check out [NYU Poly](http://engineering.nyu.edu/academics/departments/computer/). They offer concentrations in cybersecurity and we collaborate with them frequently through their [Hacker in Residence](http://www.isis.poly.edu/hackers-in-residence) program.
16+
If you're interested in taking a course like this one for credit, check out [NYU Poly](https://engineering.nyu.edu/academics/departments/computer-science-and-engineering). They offer concentrations in cybersecurity and we collaborate with them frequently through their [Hacker in Residence](https://web.archive.org/web/20170409054057/http://www.isis.poly.edu/hackers-in-residence) program.
1717

1818
# Contributing
19-
If you want to make a contribution, simply commit your new markdown to the `master` branch and we'll take it from there. Gitbook has a fantastic [editor](https://github.com/GitbookIO/editor/releases) available to help preview your changes. We're always looking for new or refined content, so please send us your suggestions!
19+
If you want to make a contribution, simply commit your new markdown to the `master` branch and we'll take it from there. We're always looking for new or refined content, so please send us your suggestions!
2020

21-
## Gitbook Usage
22-
The CTF Field Guide is built with [Gitbook](https://github.com/GitbookIO/gitbook), a command line tool for building books with Git and Markdown. You can use Gitbook to output the CTF Field Guide as a PDF, an eBook or a single, printable HTML page. Make sure you have [NodeJS](http://nodejs.org/) and `npm` on your operating system, then install Gitbook and a few of its plugins:
21+
## mdBook Usage
22+
The CTF Field Guide is built with [mdBook](https://rust-lang.github.io/mdBook/), a command line tool for building books with Git and Markdown. Refer to [mdBook's installation page](https://rust-lang.github.io/mdBook/guide/installation.html) to get it set up.
2323

24-
```
25-
npm install gitbook gitbook-plugin-ga gitbook-pdf ebook-convert -g
26-
```
24+
With mdBook installed, you can run any of these commands from within the book directory:
25+
* Generate an interactive, static website: ```mdbook build```
26+
* Serve the book via HTTP, to locally browse and edit it: ```mdbook serve```.
2727

28-
With Gitbook installed, you can run any of these commands from within the book directory:
29-
* Generate an interactive, static website: ```gitbook build ./myrepo```
30-
* Generate a single page website: ```gitbook build ./myrepo -f page```.
31-
* Generate a PDF: ```gitbook pdf ./myrepo```. Requires [gitbook-pdf](https://github.com/GitbookIO/gitbook-pdf).
32-
* Generate an eBook: ```gitbook ebook ./myrepo```. Requires [ebook-convert](http://manual.calibre-ebook.com/cli/ebook-convert.html).
28+
Third-party plugins also exist if you wish to export the book as EPUB or PDF.

‎docs/.gitignore‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

0 commit comments

Comments
 (0)