Add anchor links to headings #159

Merged
n merged 2 commits from anchor-links into master 6 months ago
  1. 19
      .eleventy.js
  2. 4
      assets/css/codeberg-docs.css
  3. 2
      content/advanced/migrating-repos.md
  4. 2
      content/collaborating/citable-code.md
  5. 6
      content/collaborating/create-organization.md
  6. 4
      content/getting-started/first-repository.md
  7. 1
      content/getting-started/install-git.md
  8. 2
      content/git/using-tags.md
  9. 6
      content/improving-codeberg/docs-contributor-faq.md
  10. 11
      content/security/gpg-key.md
  11. 19
      package-lock.json
  12. 3
      package.json

19
.eleventy.js

@ -2,6 +2,8 @@ const navigationPlugin = require("@11ty/eleventy-navigation")
const syntaxHighlightingPlugin = require("@11ty/eleventy-plugin-syntaxhighlight")
const markdownIt = require('markdown-it');
const markdownItClass = require('@toycode/markdown-it-class');
const markdownItAnchor = require('markdown-it-anchor')
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(navigationPlugin)
@ -18,10 +20,19 @@ module.exports = function(eleventyConfig) {
blockquote: 'alert'
};
const md = markdownIt({ linkify: false, html: true });
md.use(markdownItClass, mapping);
eleventyConfig.setLibrary('md', md);
const mdOptions = { linkify: false, html: true };
const mdAnchorOpts = {
permalink: markdownItAnchor.permalink.headerLink(),
permalinkClass: 'ml-5', permalinkSymbol: '#', level: [1, 2, 3, 4]
}
eleventyConfig.setLibrary(
'md',
markdownIt(mdOptions)
.use(markdownItClass, mapping)
.use(markdownItAnchor, mdAnchorOpts)
)
return {
dir: {
input: "content"

4
assets/css/codeberg-docs.css

@ -8,6 +8,10 @@
.content ol { list-style: decimal outside; padding-left: 2em; }
.content ul { list-style: outside; padding-left: 2em; }
a.header-anchor, a.header-anchor:visited { color: var(--lm-base-text-color) !important; text-decoration: none; }
.dark-mode a.header-anchor, .dark-mode a.header-anchor:visited { color: var(--dm-base-text-color) !important; text-decoration: none; }
a.header-anchor:hover { text-decoration: underline; }
/* Apply code style to generic code */
pre:not([class*="language-"]) {
background: #2E3440;

2
content/advanced/migrating-repos.md

@ -47,7 +47,7 @@ Here's an explanation of some fields on the [Gitea migration page](https://codeb
- **Access Token**: You will paste the access token generated here. An access token is required to migrate metadata.
- **Migration Items**: Here you can select the metadata you want migrated.
<h2 class="content-title" id=starting-migration>Starting Migration</h2>
## Starting Migration
Once you've filled out all the fields, click the `Migrate Repository` button.
Migration might take a while, depending on how large the repo is.

2
content/collaborating/citable-code.md

@ -11,7 +11,7 @@ The third option, which actually complements the second, is to assign a [Digital
This page will show you how to do just that. The process can be decomposed in four steps.
<h2 class="content-title" id="creating-a-release"> Create a release of your repository</h2>
## Create a release of your repository
Creating a release is optional but recommended. The reason is simply that a release will make it explicit what version of your code you want to share/cite. Any further edits to your code will not be included in the release. In other words, it is good practice to share/cite a release with fixed code rather than the always changing code of your repository.
To create a release, first go to the `Releases` tab of your repository, and click on `New Release`:

6
content/collaborating/create-organization.md

@ -13,7 +13,6 @@ Everyone can create organizations on Codeberg for free. The following sections w
> Details about the roles involved (owner, admin, member...) are given in the section [Access rights](#access-rights) below.
<a name="create-orga"></a>
## Create an Organization
On your Dashboard, click on the `+` next to your avatar and select `New Organization`:
@ -79,7 +78,6 @@ In the `Labels` tab, you can create labels that will be used across all reposito
In the top right corner, you have access to the people (members) and teams of your organization. These can also be accessed from the organization's page.
<a name="teams"></a>
## Teams
The `Teams` tab gives you an overview of the different teams, of their members and of their number of repositories. You can also join a team from there if you have the permission to do so:
@ -99,7 +97,7 @@ Click the green `+ New Team` to create a new team. Define its name, permissions
You can choose whether members of the team can only access some repositories explicitly added to the team, or whether they can access all repositories of the organziation.
You can also allow members to be able to create new repositories for the organization.
If you have allowed repository administrators to grant or remove access for teams (see [Create an Organization](#create-orga) above), they can do so in `Settings > Collaborators` tab of the repository.
If you have allowed repository administrators to grant or remove access for teams (see [Create an Organization](#create-an-organization) above), they can do so in `Settings > Collaborators` tab of the repository.
If you choose either `Read` or `Write` access, you can additionally define which sections of the repositories (code, issues, pull requests, releases and wiki) the members will have (read or write) access to. On the other hand, `Administrator` access automatically grants read and write access to all sections; this part of the form is therefore hidden in this case.
See the section [Access rights](#access-rights) below for details.
@ -113,7 +111,6 @@ If you belong to the team `Owners`, you can edit a team. For this, go to the `Te
Click on `Settings` to edit the team as shown above for the creation of a team.
This is also where you can add or remove members to a team, and assign repositories to a team.
<a name="people"></a>
## People
On the `People` tab, you can get an overview of all the people who belong to your organization:
@ -135,7 +132,6 @@ It is also shown here whether each member has activated the two-factor authentif
Finally, you can choose to leave the organization from here.
<a name="access-rights"></a>
## Access rights
An overview of the repository permissions in given in the article [Repository Permissions](/collaborating/repo-permissions).

4
content/getting-started/first-repository.md

@ -46,7 +46,7 @@ Here's an explanation of the form's fields:
It's okay to only specify owner and repository name, if you want to get started quickly.
After filling out the form, click the green "Create Repository" button on the bottom of the form.
You should now see a screen similar to the one below. If you haven't chosen to auto-generate `LICENSE`, `README` and `.gitignore` the screen might show instructions instead, which will vanish after [your first commit](#first-commit).
You should now see a screen similar to the one below. If you haven't chosen to auto-generate `LICENSE`, `README` and `.gitignore` the screen might show instructions instead, which will vanish after [your first commit](#making-your-first-commit).
<picture>
<source srcset="/assets/images/getting-started/first-repository/create-repo-3.webp" type="image/webp">
@ -141,8 +141,6 @@ knut@iceberg:~/my-project$ git remote add origin https://codeberg.org/knut/fooba
This command has no output on the command line.
<a name="first-commit"></a>
## Making your first commit
Now that you've connected your repository to your local development copy, it is time to make your first commit.

1
content/getting-started/install-git.md

@ -110,7 +110,6 @@ Alternatively, you can also download the installer from the Git website as expla
If you want to keep all your previous settings, simply tick the box `Only show new options` in the installation wizard (see screenshots above).
<a name="git-clients"></a>
## Git clients
Git can be used from the command line as shown above, but it can also be used through graphical user interfaces called *Git clients*.
You can find a list of some available Git clients on the [Git website](https://git-scm.com/downloads/guis).

2
content/git/using-tags.md

@ -27,7 +27,7 @@ git tag -a <version number here> -m "<my tag name>"
```
### On Codeberg
See the [creating a release](/collaborating/citable-code/#creating-a-release) segment on the citable code article for instructions on creating tags and releases on Codeberg.
See the [creating a release](/collaborating/citable-code/#create-a-release-of-your-repository) segment on the citable code article for instructions on creating tags and releases on Codeberg.
## Finding and viewing releases in a repository
<picture>

6
content/improving-codeberg/docs-contributor-faq.md

@ -17,7 +17,7 @@ Then, for each major contribution that you want to make (e.g. for each new artic
The Codeberg Documentation collaborators will then review your pull request, they may request some changes and eventually, once all is good, they may merge your contribution into the official repository and deploy it to the live site.
### How to create a new article?
To write a new article, create a new Markdown file next to the existing files in the section that you want to put your article in. So, if for example you want to create an article called "Keeping your repo clean with .gitignore" in the "Working with Git Repositories" section, put a new file called for example `gitignore.md` into the `content/git` directory. Please adhere to the [file naming conventions](#file-naming-conventions).
To write a new article, create a new Markdown file next to the existing files in the section that you want to put your article in. So, if for example you want to create an article called "Keeping your repo clean with .gitignore" in the "Working with Git Repositories" section, put a new file called for example `gitignore.md` into the `content/git` directory. Please adhere to the [file naming conventions](#how-should-files-be-named%3F).
Review

can special chars be stripped, or does this work cleanly?

can special chars be stripped, or does this work cleanly?
n commented 6 months ago
Review

Special characters in the links have to be encoded. Removing it would break the link.

Special characters in the links have to be [encoded](https://en.wikipedia.org/wiki/Percent-encoding). Removing it would break the link.
n commented 6 months ago
Review

Each sub-heading also links to its permalink.

Each sub-heading also links to its permalink.
Review

yeah, I was wondering if it was easier to strip them from the title (just as spaces are turned into dashes), so they are completely dropped from the links. But it's fine if it works this way.

yeah, I was wondering if it was easier to strip them from the title (just as spaces are turned into dashes), so they are completely dropped from the links. But it's fine if it works this way.
Then, add the `eleventyNavigation` header to your newly created file. That header contains information about the article's place in the structure of the site.
@ -58,7 +58,7 @@ Yes, but currently only if you're working with a local clone of the repository.
It is recommended to set this up, because it can help you a lot in spotting errors that would otherwise go unnoticed, especially aesthetic errors and broken links.
<h3 class="content-title" id="file-naming-conventions">How should files be named?</h3>
### How should files be named?
Please adhere to [kebab-Case](https://en.wikipedia.org/wiki/Kebab_case) naming rules for any files in Codeberg Documentation.
@ -86,7 +86,7 @@ Otherwise, feel free to request screenshots being added when merging your PR. Fo
On the technical side, screenshots should ideally be available in both the WebP
and PNG formats (WebP and JPEG for photographs), they should be in a large enough resolution so that text is clearly
readable and their filenames should follow Codeberg Documentation's [naming conventions](#file-naming-conventions).
readable and their filenames should follow Codeberg Documentation's [naming conventions](#how-should-files-be-named%3F).
Please put screenshots under `assets/images/[section]/[article]/...` where `[section]` and `[article]` are the kebab-cased names of the section or your article, respectively.

11
content/security/gpg-key.md

@ -9,17 +9,17 @@ eleventyNavigation:
GPG stands for GNU Privacy Guard, which is an open-source cryptographic software program and uses an implementation of the [Open PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) standard. A GPG key is used to sign each commit you make so your collaborators can be sure it was you who made it.
## Adding an Existing GPG key
If you have your public key in an easy to find location, great! You can skip to [adding it to your account](#Adding-to-Codeberg). If not we will be using the [GnuPG software](https://gnupg.org/download/index.html#binary) to check, if you have downloaded this before you can skip to [Generating a GPG key](#Generating).
If you have your public key in an easy to find location, great! You can skip to [adding it to your account](#adding-your-gpg-key-to-codeberg). If not we will be using the [GnuPG software](https://gnupg.org/download/index.html#binary) to check, if you have downloaded this before you can skip to [Generating a GPG key](#generating-a-gpg-key).
1. Download and install [GnuPG](https://gnupg.org/download/index.html#binary).
> If you are using a Linux distro this might already be installed, check by typing `gpg --version` in the terminal.
2. Type `gpg --list-secret-keys --keyid-format LONG` into your terminal, it will list all the keys that you have both a public and private key for.
3. Check the output for a key that you want, if there are none, or none that you want to use, continue to [Generating a GPG key](#toc_2). If there is one that you want to use, skip to [adding it to your account](#Adding-to-Codeberg).
3. Check the output for a key that you want, if there are none, or none that you want to use, continue to [Generating a GPG key](#generating-a-gpg-key). If there is one that you want to use, skip to [adding it to your account](#adding-your-gpg-key-to-codeberg).
> **IMPORTANT**
> Be sure that your selected key uses the same email as your Codeberg account.
<h2 class="content-title" id=Generating>Generating a GPG key</h2>
## Generating a GPG key
If you haven’t already, be sure to [install](https://gnupg.org/download/index.html#binary) GnuPG, as you will be using it to generate your keys.
1. Type `gpg --full-generate-key` into your terminal
@ -30,7 +30,7 @@ If you haven’t already, be sure to [install](https://gnupg.org/download/index.
6. Enter your information, be sure to use the same email as your Codeberg account
7. Type in a passphrase, make sure you write it down somewhere safe. You'll need it later to add your key to Git or revoke it if it is compromised
<h2 class="content-title" id=Adding-to-Codeberg>Adding your GPG key to Codeberg</h2>
## Adding your GPG key to Codeberg
1. Type `gpg --list-secret-keys --keyid-format LONG` into the terminal
2. Select the key you would like to use (the one you just generated). In this example, the GPG key ID is `3AA5C34371567BD2`:
@ -47,7 +47,8 @@ ssb rsa4096/42B317FD4BA89E7A 2021-06-06 [E] [expires: 2022-06-06]
4. Copy the output including the `-----BEGIN PGP PUBLIC KEY BLOCK-----` and `-----END PGP PUBLIC KEY BLOCK-----`
5. Go to the [SSH/GPG Keys tab](https://codeberg.org/user/settings/keys) in your Codeberg settings.
6. Click `Add Key` in the `Manage GPG Keys` section, paste in your public key and click the `Add Key` button.
<h2 class="content-title" id=Adding-to-git>Telling Git about your GPG key</h2>
## Telling Git about your GPG key
In order for you to use your key you will also need to tell Git about it.
1. Open your terminal

19
package-lock.json

@ -9,7 +9,8 @@
"@11ty/eleventy": "^0.12.1",
"@11ty/eleventy-navigation": "^0.1.6",
"@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1",
"@toycode/markdown-it-class": "^1.2.4"
"@toycode/markdown-it-class": "^1.2.4",
"markdown-it-anchor": "^8.1.2"
}
},
"node_modules/@11ty/dependency-tree": {
@ -2031,6 +2032,15 @@
"markdown-it": "bin/markdown-it.js"
}
},
"node_modules/markdown-it-anchor": {
"version": "8.1.2",
"resolved": "https://registry.npmjs.org/markdown-it-anchor/-/markdown-it-anchor-8.1.2.tgz",
"integrity": "sha512-9D58TKK4dakqmjcmVuqHoB3ntKBpQJ0Ld38B83aiHJcBD72IZIyPjNtihPA6ayRI5WD33e1W68mArliNLHCprg==",
"dev": true,
"peerDependencies": {
"markdown-it": "*"
}
},
"node_modules/maximatch": {
"version": "0.1.0",
"resolved": "https://registry.npmjs.org/maximatch/-/maximatch-0.1.0.tgz",
@ -5435,6 +5445,13 @@
"uc.micro": "^1.0.5"
}
},
"markdown-it-anchor": {
"version": "8.1.2",
"resolved": "https://registry.npmjs.org/markdown-it-anchor/-/markdown-it-anchor-8.1.2.tgz",
"integrity": "sha512-9D58TKK4dakqmjcmVuqHoB3ntKBpQJ0Ld38B83aiHJcBD72IZIyPjNtihPA6ayRI5WD33e1W68mArliNLHCprg==",
"dev": true,
"requires": {}
},
"maximatch": {
"version": "0.1.0",
"resolved": "https://registry.npmjs.org/maximatch/-/maximatch-0.1.0.tgz",

3
package.json

@ -12,6 +12,7 @@
"@11ty/eleventy": "^0.12.1",
"@11ty/eleventy-navigation": "^0.1.6",
"@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1",
"@toycode/markdown-it-class": "^1.2.4"
"@toycode/markdown-it-class": "^1.2.4",
"markdown-it-anchor": "^8.1.2"
}
}

Loading…
Cancel
Save