The Hacker Recipes

Appearance

Guide for authors ​

As an author contributing to this project, it's essential to follow a consistent structure to ensure that your article is easy to read and understand. This guide outlines the typical structure, file organization, and best practices for writing articles that align with the project's standards.

Files and folders ​

All articles are stored in the /docs/src folder.

If the article doesn't include images (or other assets), if should be a markdown file with the .md extension, and named after the topic it covers.

For the article to be included in the navigation panel, it should be added to the config.mts file, in the sidebar array, with the following structure:

typescript
{
  "text": 'Category',
  "items": [
    {
      "text": 'Article without images',
      "link": '/.../category/topic.md',
    },
    {
      "text": 'Article with images',
      "link": '/.../category/topic/index.md',
    }
  ]
}

A category can be a container for articles, and/or be a container for other categories, and include (or not) an index.md file to provide a brief introduction to the category. For the latter, the structure goes like this:

typescript
{
  "text": 'Category',
  "link": '/.../index.md'    
  "items": [
// ...

Content structure ​

A typical article in this project follows a three-part structure:

  1. Theory: provides an introduction to the topic, adds context, explains the concepts and ideas behind it.
  2. Practice: delves into the practical aspects: step-by-step explanations and examples, with commands and code snippets. This part should include, whenever possible, a tabs block with one tab for Unix-like commands, and another for Windows commands.
  3. Resources: lists the sources that helped build the article, and additional resources that one can use to further their learning (e.g. articles, blogposts, whitepapers, videos)

Writing style ​

When writing your article, one should keep the following tone & voice.

  • Professional and Authoritative: The content should maintain a professional tone, suitable for a technical audience familiar with cybersecurity concepts.
  • Instructional and Informative: The writing aims to educate the reader, with clear instructions and explanations. It avoids being overly casual, focusing instead on delivering detailed, technical knowledge.

Block Types ​

The project uses a variety of block types to organize and present content. While this guide focuses on the main blocks used in this project, additionnal blocks are listed in the official VitePress docs.

Code ​

Use triple backticks to delimit code blocks, specifying the language after the first set of backticks. VitePress supports extended usage of code blocks such as syntax highlighting, line highlighting, line focus, colored diffs, errors and warnings highlighting, line numbers, code groups.

But it can be as simple as that:

```python
print('hello world')
```

Giving the following output

python
print('hello world')

Tabs ​

Input

markdown
:::tabs

== tab a

Some content

== tab b

b content

:::

Output

Some content

Callouts ​

THR uses GitHub-flavored alerts to render most callouts. The most common callouts in The Hacker Recipes are:

NOTE

Note from the author, not critical to the main content. To calrify, offer references, add content or background.

TIP

Offer helpful advice or best practices. Providing shortcut or expert recommandation.

WARNING

Alert the reader to potentiel dangers. Provide OPSEC advice.

CAUTION

When there's critical information the reader needs to be aware of.

SUCCESS

When the author wants to highlight a successful outcome or scenario.

Details

Details blocks can also be used

The input for this goes like this:

markdown
> [!NOTE] NOTE
> Note from the author, not critical to the main content. To calrify, offer references, add content or background.

> [!TIP] TIP
> Offer helpful advice or best practices. Providing shortcut or expert recommandation.

> [!WARNING] WARNING
> Alert the reader to potentiel dangers. Provide OPSEC advice.

> [!CAUTION] CAUTION
> When there's critical information the reader needs to be aware of.

> [!SUCCESS] SUCCESS
> When the author wants to highlight a successful outcome or scenario.

::: details
Details blocks can also be used
:::

The title of a callout is optionnal.

> [!NOTE]
The title of a callout is optionnal.

As simple as [title](link) for links and ![](path/to/image) for images.

If there are spaces in the image path, either spaces need to be URL-encded (%20), or the following structure can be used (recommended): ![](<path/to/some image>)

Images can also be given a caption

markdown
![](path/to/image)
Some caption{.caption}

Which will output the following

Some caption

To embed a YouTube link, use the following tag format:

> [!YOUTUBE] https://www.youtube.com/watch?v=example

This will create a clickable link that directs users to the specified YouTube video.

Which will output the following

Ensure you provide the full YouTube link, as using a shortened link will cause the tag to malfunction.

Others ​

BlockDescription
LinksInternal links (to other articles, or to anchor points)
TablesTables (like this one)
EmojisEmojis 🎉

### Quotes

> "Someone said something important and it should be highlighted in the article? Please quote it and attribute it to the initial author."
>  
> _(Author, date, [source](#))_

```markdown
> "Someone said something important and it should be highlighted in the article? Please quote it and attribute it to the initial author."
>  
> _(Author, date, [source](#))_

Article template ​

An article template is available for a quick start: Template.

Highlighting contributors ​

For contributors to be listed, they need to be listed in the authors property of the frontmatter configuration of the corresponding page(s).

When contributing to a page, an author must add its GitHub username to it:

markdown
---
authors: author1, author2, ...
---

Get started 🚀 ​

  1. Fork the repository (https://github.com/The-Hacker-Recipes/The-Hacker-Recipes/fork)
  2. (optionnal) create a new branch in your fork, if you plan on working on different topics
  3. Create your content using this guide, and the template if needed
  4. Make sure the content builds fine with npm install && npm run docs:dev
  5. Make a Pull Request (https://github.com/The-Hacker-Recipes/The-Hacker-Recipes/compare)