johnyz89/personal-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: install and generate first docs in zensical
Documentation / deploy (push) Has been cancelled
Details

Browse Source
This commit is contained in:
johny
2026-05-20 08:05:03 +02:00
parent 77e9100453
commit 7322593caa
7 changed files with 647 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/docs.yml
+29
View File
@@ -0,0 +1,29 @@
name: Documentation
on:
push:
branches:
- master
- main
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- uses: actions/configure-pages@v6
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with:
python-version: 3.x
- run: pip install zensical
- run: zensical build --clean
- uses: actions/upload-pages-artifact@v5
with:
path: site
- uses: actions/deploy-pages@v5
id: deployment
.gitignore
+1
View File
@@ -0,0 +1 @@
site/
docs/index.md
+9
View File
@@ -0,0 +1,9 @@
---
icon: lucide/rocket
title: Index
---
This is Johny's personal docs generated in zensical
[zensical.org](https://zensical.org/docs/)
docs/knowledge/linux/acl.md
+248
View File
@@ -0,0 +1,248 @@
---
title: acl
---
Checking the ACL list with `getfacl`
Once you've set the acl with setfacl it is common sense to check if it took effect, in order to do so you will need to use the `getfacl` command.
``` bash
root@testvm:/var/tmp# getfacl appdir/
# file: appdir/
# owner: root
# group: appgroup
user::rwx
group::rwx
group:testusers:r--
mask::rwx
other::r-x
```
The output of getfacl is pretty self explanatory, you can see the rule that we added below the standard group entry.
Identifying files/directories that have ACL's
While the standard unix permissions are displayed with the ls -l command; the defined ACL's are a little more verbose and are not a part of the long listing. The command ls will tell you if a file or directory does have acl's, it's just not that obvious.
``` bash
root@testvm:/var/tmp# ls -la | grep appdir
drwxrwxr-x+ 2 root appgroup 4096 May 27 10:45 appdir
```
As you can see there is now a + at the end of the directories permissions. This + is the indicator that this file or directory has acl's, from here you can use the getfacl command to see what they are.
Examples of Usage
Now that we have a filesystem that supports ACL's and we know how to set and review the ACL's lets run through a few examples of ACL usage.
Use Cases
Removing all acl entries from a file or directory
Set test users to have read access to all files in a directory
Set the same acl changes recursively
Set the same acls on all newly created files automatically
Set testuser1 to have read, write and execute access to the appuser1 directory
Set all users to have read, write and execute access to the shared directory
Remove the acl for testuser1 on appuser1 directory
Removing all acl entries from a file or directory
Before we start messing with acl's in my directory I want to clear out all of the acl's it previously had. Doing this one by one can be a bit of a pain, its a good thing the setfacl command gives you the ability to remove all acl's on a specified file or directory. This can be accomplished using the -b option of setfacl.
``` bash
root@testvm:/var/tmp# getfacl appdir/
# file: appdir/
# owner: root
# group: appgroup
user::rwx
group::rwx
group:testusers:r--
mask::rwx
other::r-x
```
``` bash
root@testvm:/var/tmp# setfacl -b appdir/
root@testvm:/var/tmp# getfacl appdir/
# file: appdir/
# owner: root
# group: appgroup
user::rwx
group::rwx
other::r-x
```
Keep in mind when using the -b option that this will remove all of the acl rules on the specified directory.
Set testusers to have read access to all files in the appdir directory
This is a pretty basic acl, we want the testusers group to have read access to all files in the appdir directory.
``` bash
root@testvm:/var/tmp# setfacl -m g:testusers:r appdir/
root@testvm:/var/tmp# getfacl appdir
# file: appdir
# owner: root
# group: appgroup
user::rwx
group::rwx
group:testusers:r-- mask::rwx
other::r-x
```
Set the changes recursively
The appdir has 2 sub directories appdir/appuser1 and appdir/appuser2 in this case we want the acl rules set above to apply to these directories as well. This can easily be accomplished by adding the -R (recursive) option in setfacl. This works exactly like the recursive option for chmod.
``` bash
root@testvm:/var/tmp# setfacl -Rm g:testusers:r appdir/
root@testvm:/var/tmp# getfacl appdir/*
# file: appdir/appuser1
# owner: appuser1
# group: appgroup
user::rwx
group::r-x
group:testusers:r-- mask::r-x
other::r-x
# file: appdir/appuser2
# owner: appuser2
# group: appgroup
user::rwx
group::r-x
group:testusers:r-- mask::r-x
other::r-x
```
Set the same acl's on all newly created files automatically
The -d (default) option in setfacl is extremely useful; this option will allow us to set an acl rule to be the default rule. When this is set on a directory this makes all new files or directories created within that directory inherit the same acl rules.
``` bash
root@testvm:/var/tmp# setfacl -dm g:testusers:r appdir/
root@testvm:/var/tmp# touch appdir/file1
root@testvm:/var/tmp# mkdir appdir/dir1
root@testvm:/var/tmp# getfacl appdir/*
# file: appdir/appuser1
# owner: appuser1
# group: appgroup
user::rwx
group::r-x
group:testusers:r--
mask::r-x
other::r-x
# file: appdir/appuser2
# owner: appuser2
# group: appgroup
user::rwx
group::r-x
group:testusers:r--
mask::r-x
other::r-x
# file: appdir/dir1
# owner: root
# group: root
user::rwx
group::rwx
group:testusers:r-- mask::rwx
other::r-x
default:user::rwx
default:group::rwx
default:group:testusers:r-- default:mask::rwx
default:other::r-x
# file: appdir/file1
# owner: root
# group: root
user::rw-
group::rwx #effective:rw-
group:testusers:r-- mask::rw-
other::r--
```
As you can see dir1 also have the default acl rules as appdir, yet appuser1 does not. This is because we did not set the default recursively; this can be done by using the -R option.
``` bash
root@testvm:/var/tmp# setfacl -Rdm g:testusers:r appdir/
root@testvm:/var/tmp# getfacl appdir/appuser1
# file: appdir/appuser1
# owner: appuser1
# group: appgroup
user::rwx
group::r-x
group:testusers:r--
mask::r-x
other::r-x
default:user::rwx
default:group::r-x
default:group:testusers:r--
default:mask::r-x
default:other::r-x
```
Set testuser1 to have read, write and execute access to the appuser1 directory
While the user testuser1 is in the testusers group and has read access to the appuser1 directory he does not have write access. In this case we want to give him write access without giving the rest of the testusers write access. This can be done using acl's by specifying a specific user rather than a group.
``` bash
root@testvm:/var/tmp# setfacl -m u:testuser1:rwx appdir/
root@testvm:/var/tmp# getfacl appdir/
# file: appdir/
# owner: root
# group: appgroup
user::rwx
user:testuser1:rwx group::rwx
group:testusers:r--
mask::rwx
other::r-x
default:user::rwx
default:group::rwx
default:group:testusers:r--
default:mask::rwx
default:other::r-x
```
The user testuser1 can now create files in the appdir1 directory.
``` bash
root@testvm:/var/tmp# sudo -u testuser1 touch appdir/file2
root@testvm:/var/tmp# ls -la appdir/file2
-rw-rw-r--+ 1 testuser1 testusers 0 May 27 12:17 appdir/file2
```
Set all users to have read, write and execute to the shared directory
We have now given users and groups permissions on directories and files, but what happens when we want all users to have access to a directory? Adding every users name or group could get tedious, in this case we can set the "other" or "world" permissions so that all users on a system can access this directory.
``` bash
root@testvm:/var/tmp# setfacl -m o::rwx shared
root@testvm:/var/tmp# getfacl shared/
# file: shared/
# owner: root
# group: root
user::rwx
group::r-x
other::rwx
```
You might be asking yourself right now "wait a minute, did setfacl just set the permissions to 757?"; why yes it did! ACL's are just an extension of the standard unix permissions, in this case because we are not specifying a user or group; setfacl will simply just change the mode of the file. Tricky, yes I know.
Remove the acl for testuser1 on appuser1 directory
Unlike the -b option that removes all acl's on a directory or file the -x option will only remove the specified rule. This is useful for when you maybe fat fingered an acl rule and don't want to completely remove all of the acl rules attached to that file/directory.
``` bash
root@testvm:/var/tmp# setfacl -x u:testuser1 appdir/
root@testvm:/var/tmp# getfacl appdir/
# file: appdir/
# owner: root
# group: appgroup
user::rwx
group::rwx
group:testusers:r--
mask::rwx
other::r-x
default:user::rwx
default:group::rwx
default:group:testusers:r--
default:mask::rwx
default:other::r-x
```
docs/knowledge/linux/zensical.md
+11
View File
@@ -0,0 +1,11 @@
---
title: zensical
---
To run local zensical server go to procjet dir, activate venv and run serve:
``` bash
cd ~/git/personal-wiki
source .venv/bin/activate
zensical serve
```
index.md
-1
View File
@@ -1 +0,0 @@
This is where wiki starts
zensical.toml
+349
View File
@@ -0,0 +1,349 @@
# ============================================================================
#
# The configuration produced by default is meant to highlight the features
# that Zensical provides and to serve as a starting point for your own
# projects.
#
# ============================================================================
[project]
# The site_name is shown in the page header and the browser window title
#
# Read more: https://zensical.org/docs/setup/basics/#site_name
site_name = "johnyz89 personal wiki"
# The site_description is included in the HTML head and should contain a
# meaningful description of the site content for use by search engines.
#
# Read more: https://zensical.org/docs/setup/basics/#site_description
site_description = "My personal wiki project, where all the knowledge lays"
# The site_author attribute. This is used in the HTML head element.
#
# Read more: https://zensical.org/docs/setup/basics/#site_author
site_author = "<johynz89>"
# The site_url is the canonical URL for your site. When building online
# documentation you should set this.
# Read more: https://zensical.org/docs/setup/basics/#site_url
site_url = "https://docs.wolfrasoft.com/"
# The copyright notice appears in the page footer and can contain an HTML
# fragment.
#
# Read more: https://zensical.org/docs/setup/basics/#copyright
copyright = """
Copyright &copy; 2026 The authors
"""
# Zensical supports both implicit navigation and explicitly defined navigation.
# If you decide not to define a navigation here then Zensical will simply
# derive the navigation structure from the directory structure of your
# "docs_dir". The definition below demonstrates how a navigation structure
# can be defined using TOML syntax.
#
# Read more: https://zensical.org/docs/setup/navigation/
# nav = [
# { "Get started" = "index.md" },
# { "Markdown in 5min" = "markdown.md" },
# ]
# With the "extra_css" option you can add your own CSS styling to customize
# your Zensical project according to your needs. You can add any number of
# CSS files.
#
# The path provided should be relative to the "docs_dir".
#
# Read more: https://zensical.org/docs/customization/#additional-css
#
#extra_css = ["stylesheets/extra.css"]
# With the `extra_javascript` option you can add your own JavaScript to your
# project to customize the behavior according to your needs.
#
# The path provided should be relative to the "docs_dir".
#
# Read more: https://zensical.org/docs/customization/#additional-javascript
#extra_javascript = ["javascripts/extra.js"]
# ----------------------------------------------------------------------------
# Section for configuring theme options
# ----------------------------------------------------------------------------
[project.theme]
# change this to "classic" to use the traditional Material for MkDocs look.
#variant = "classic"
# Zensical allows you to override specific blocks, partials, or whole
# templates as well as to define your own templates. To do this, uncomment
# the custom_dir setting below and set it to a directory in which you
# keep your template overrides.
#
# Read more:
# - https://zensical.org/docs/customization/#extending-the-theme
#
#custom_dir = "overrides"
# With the "favicon" option you can set your own image to use as the icon
# browsers will use in the browser title bar or tab bar. The path provided
# must be relative to the "docs_dir".
#
# Read more:
# - https://zensical.org/docs/setup/logo-and-icons/#favicon
# - https://developer.mozilla.org/en-US/docs/Glossary/Favicon
#
#favicon = "images/favicon.png"
# Zensical supports more than 60 different languages. This means that the
# labels and tooltips that Zensical's templates produce are translated.
# The "language" option allows you to set the language used. This language
# is also indicated in the HTML head element to help with accessibility
# and guide search engines and translation tools.
#
# The default language is "en" (English). It is possible to create
# sites with multiple languages and configure a language selector. See
# the documentation for details.
#
# Read more:
# - https://zensical.org/docs/setup/language/
#
language = "en"
# Zensical provides a number of feature toggles that change the behavior
# of the documentation site.
features = [
# Zensical includes an announcement bar. This feature allows users to
# dismiss it when they have read the announcement.
# https://zensical.org/docs/setup/header/#announcement-bar
"announce.dismiss",
# If you have a repository configured and turn on this feature, Zensical
# will generate an edit button for the page. This works for common
# repository hosting services.
# https://zensical.org/docs/setup/repository/#content-actions
#"content.action.edit",
# If you have a repository configured and turn on this feature, Zensical
# will generate a button that allows the user to view the Markdown
# code for the current page.
# https://zensical.org/docs/setup/repository/#content-actions
#"content.action.view",
# Code annotations allow you to add an icon with a tooltip to your
# code blocks to provide explanations at crucial points.
# https://zensical.org/docs/authoring/code-blocks/#code-annotations
"content.code.annotate",
# This feature turns on a button in code blocks that allow users to
# copy the content to their clipboard without first selecting it.
# https://zensical.org/docs/authoring/code-blocks/#code-copy-button
"content.code.copy",
# Code blocks can include a button to allow for the selection of line
# ranges by the user.
# https://zensical.org/docs/authoring/code-blocks/#code-selection-button
"content.code.select",
# Zensical can render footnotes as inline tooltips, so the user can read
# the footnote without leaving the context of the document.
# https://zensical.org/docs/authoring/footnotes/#footnote-tooltips
"content.footnote.tooltips",
# If you have many content tabs that have the same titles (e.g., "Python",
# "JavaScript", "Cobol"), this feature causes all of them to switch to
# at the same time when the user chooses their language in one.
# https://zensical.org/docs/authoring/content-tabs/#linked-content-tabs
"content.tabs.link",
# With this feature enabled users can add tooltips to links that will be
# displayed when the mouse pointer hovers the link.
# https://zensical.org/docs/authoring/tooltips/#improved-tooltips
"content.tooltips",
# With this feature enabled, Zensical will automatically hide parts
# of the header when the user scrolls past a certain point.
# https://zensical.org/docs/setup/header/#automatic-hiding
# "header.autohide",
# Turn on this feature to expand all collapsible sections in the
# navigation sidebar by default.
# https://zensical.org/docs/setup/navigation/#navigation-expansion
# "navigation.expand",
# This feature turns on navigation elements in the footer that allow the
# user to navigate to a next or previous page.
# https://zensical.org/docs/setup/footer/#navigation
"navigation.footer",
# When section index pages are enabled, documents can be directly attached
# to sections, which is particularly useful for providing overview pages.
# https://zensical.org/docs/setup/navigation/#section-index-pages
"navigation.indexes",
# When instant navigation is enabled, clicks on all internal links will be
# intercepted and dispatched via XHR without fully reloading the page.
# https://zensical.org/docs/setup/navigation/#instant-navigation
"navigation.instant",
# With instant prefetching, your site will start to fetch a page once the
# user hovers over a link. This will reduce the perceived loading time
# for the user.
# https://zensical.org/docs/setup/navigation/#instant-prefetching
"navigation.instant.prefetch",
# In order to provide a better user experience on slow connections when
# using instant navigation, a progress indicator can be enabled.
# https://zensical.org/docs/setup/navigation/#progress-indicator
#"navigation.instant.progress",
# When navigation paths are activated, a breadcrumb navigation is rendered
# above the title of each page
# https://zensical.org/docs/setup/navigation/#navigation-path
"navigation.path",
# When pruning is enabled, only the visible navigation items are included
# in the rendered HTML, reducing the size of the built site by 33% or more.
# https://zensical.org/docs/setup/navigation/#navigation-pruning
#"navigation.prune",
# When sections are enabled, top-level sections are rendered as groups in
# the sidebar for viewports above 1220px, but remain as-is on mobile.
# https://zensical.org/docs/setup/navigation/#navigation-sections
"navigation.sections",
# When tabs are enabled, top-level sections are rendered in a menu layer
# below the header for viewports above 1220px, but remain as-is on mobile.
# https://zensical.org/docs/setup/navigation/#navigation-tabs
#"navigation.tabs",
# When sticky tabs are enabled, navigation tabs will lock below the header
# and always remain visible when scrolling down.
# https://zensical.org/docs/setup/navigation/#sticky-navigation-tabs
#"navigation.tabs.sticky",
# A back-to-top button can be shown when the user, after scrolling down,
# starts to scroll up again.
# https://zensical.org/docs/setup/navigation/#back-to-top-button
"navigation.top",
# When anchor tracking is enabled, the URL in the address bar is
# automatically updated with the active anchor as highlighted in the table
# of contents.
# https://zensical.org/docs/setup/navigation/#anchor-tracking
"navigation.tracking",
# When search highlighting is enabled and a user clicks on a search result,
# Zensical will highlight all occurrences after following the link.
# https://zensical.org/docs/setup/search/#search-highlighting
"search.highlight",
# When anchor following for the table of contents is enabled, the sidebar
# is automatically scrolled so that the active anchor is always visible.
# https://zensical.org/docs/setup/navigation/#anchor-following
# "toc.follow",
# When navigation integration for the table of contents is enabled, it is
# always rendered as part of the navigation sidebar on the left.
# https://zensical.org/docs/setup/navigation/#navigation-integration
#"toc.integrate",
]
# ----------------------------------------------------------------------------
# You can configure your own logo to be shown in the header using the "logo"
# option in the "theme" subsection. The logo must be a relative path to a file
# in your "docs_dir", e.g., to use `docs/assets/logo.png` you would set:
# ----------------------------------------------------------------------------
#logo = "assets/logo.png"
# ----------------------------------------------------------------------------
# If you don't have a dedicated project logo, you can use a built-in icon from
# the icon sets shipped in Zensical. Please note that the setting lives in a
# different subsection, and that the above take precedence over the icon.
#
# Read more:
# - https://zensical.org/docs/setup/logo-and-icons
# - https://github.com/zensical/ui/tree/master/dist/.icons
# ----------------------------------------------------------------------------
#[project.theme.icon]
#logo = "lucide/smile"
# ----------------------------------------------------------------------------
# In the "font" subsection you can configure the fonts used. By default, fonts
# are loaded from Google Fonts, giving you a wide range of choices from a set
# of suitably licensed fonts. There are options for a normal text font and for
# a monospaced font used in code blocks.
# ----------------------------------------------------------------------------
#[project.theme.font]
#text = "Inter"
#code = "Jetbrains Mono"
# ----------------------------------------------------------------------------
# In the "palette" subsection you can configure options for the color scheme.
# You can configure different color schemes, e.g., to turn on dark mode,
# that the user can switch between. Each color scheme can be further
# customized.
#
# Read more:
# - https://zensical.org/docs/setup/colors/
# ----------------------------------------------------------------------------
[[project.theme.palette]]
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"
[[project.theme.palette]]
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to light mode"
# ----------------------------------------------------------------------------
# The "extra" section contains miscellaneous settings.
# ----------------------------------------------------------------------------
#[[project.extra.social]]
#icon = "fontawesome/brands/github"
#link = "https://github.com/user/repo"
# ----------------------------------------------------------------------------
# In this section you can configure the Markdown extensions that are used when
# rendering your documentation. We enable the most useful extensions by default,
# but you can customize this list to your needs.
#
# Read more:
# - https://zensical.org/docs/setup/extensions/
# ----------------------------------------------------------------------------
[project.markdown_extensions.abbr]
[project.markdown_extensions.admonition]
[project.markdown_extensions.attr_list]
[project.markdown_extensions.def_list]
[project.markdown_extensions.footnotes]
[project.markdown_extensions.md_in_html]
[project.markdown_extensions.toc]
permalink = true
[project.markdown_extensions.pymdownx.arithmatex]
generic = true
[project.markdown_extensions.pymdownx.betterem]
[project.markdown_extensions.pymdownx.caret]
[project.markdown_extensions.pymdownx.details]
[project.markdown_extensions.pymdownx.emoji]
emoji_generator = "zensical.extensions.emoji.to_svg"
emoji_index = "zensical.extensions.emoji.twemoji"
[project.markdown_extensions.pymdownx.highlight]
anchor_linenums = true
line_spans = "__span"
pygments_lang_class = true
[project.markdown_extensions.pymdownx.inlinehilite]
[project.markdown_extensions.pymdownx.keys]
[project.markdown_extensions.pymdownx.magiclink]
[project.markdown_extensions.pymdownx.mark]
[project.markdown_extensions.pymdownx.smartsymbols]
[project.markdown_extensions.pymdownx.superfences]
custom_fences = [
{ name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" }
]
[project.markdown_extensions.pymdownx.tabbed]
alternate_style = true
combine_header_slug = true
[project.markdown_extensions.pymdownx.tasklist]
custom_checkbox = true
[project.markdown_extensions.pymdownx.tilde]