From 89c0a4dca9c289652fe21cdc59057eb2b4a3d757 Mon Sep 17 00:00:00 2001 From: a Date: Sun, 11 Dec 2022 18:07:55 -0600 Subject: [PATCH] add basic docs/readme on functionality --- README.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..07f998a --- /dev/null +++ b/README.md @@ -0,0 +1,136 @@ +# hugo-theme-paradox + +Paradox is a theme for Hugo intended documentation sites. + +## Features and recommendations + +### config.toml + +general config settings you might want to use + +```toml +baseURL = 'https://docs.pixelfed.org/' +languageCode = 'en-us' +title = 'Pixelfed Documentation' +theme = 'paradox' +defaultContentLanguage = 'en' +enableGitInfo = true + +disableKinds = ["taxonomy"] +ignoreErrors = ["error-disable-taxonomy"] + +[languages] +[languages.en] +contentDir = 'content/en' +languageName = 'English' +weight = 1 + +[frontmatter] +lastmod = ["lastmod", ":git", "date", "publishDate"] + +[markup.tableOfContents] +ordered = true + +[markup.goldmark.renderer] +unsafe = true + +[markup.highlight] +codeFences = true +lineNumbersInTable = false +tabWidth = 3 +noClasses = false +``` + +To get search working: + +```toml +[outputs] +home = ["HTML", "RSS", "JSON"] +page = ["HTML"] +``` + +Theme-specific features and parameters: + +```toml +[params] +icon = "https://avatars0.githubusercontent.com/u/38410642?s=200&v=4" +title = "Pixelfed documentation" # sets the header title separately from metadata (may be removed in the future? idk if the top-level title should always be the same) +forge = "github" # github, gitea +# forgeUrl = "https://git.trwnh.com" # if set to gitea +repo = "pixelfed/docs" # the path to the repo +branch = "main" # the branch to use for edits +autonumbering = true # global default for whether to autonumber section headings (can also be used on a per-page level via frontmatter params) +# borders = true # whether to use borders to separate the layout +``` + +main menu (goes in header for now) + +```toml +[menu] +[[menu.main]] +identifier = 'pixelfed' +name = 'pixelfed.org' +url = 'https://pixelfed.org' +weight = 10 +pre = '' + +[[menu.main]] +identifier = 'github' +name = 'pixelfed/docs' +url = 'https://github.com/pixelfed/docs' +weight = 20 +pre = '' +``` + +you can also put a simple/short menu in the footer (currently intended for attribution info) + +```toml +[[menu.footer]] +identifier = "copyright" +name = "CC BY-SA 4.0" +url = "https://creativecommons.org/licenses/by-sa/4.0/" +weight = 10 +pre = '' +``` + +next to the footer menu there is a social menu intended for icon links + +```toml +[[menu.social]] +identifier = "mastodon" +pre = '' +url = "https://mastodon.social/@pixelfed" +weight = 10 + +[[menu.social]] +identifier = "pixelfed" +pre = '' +url = "https://pixelfed.social/pixelfed" +weight = 15 + +[[menu.social]] +identifier = "twitter" +pre = '' +url = "https://twitter.com/pixelfed" +weight = 20 + +[[menu.social]] +identifier = "github" +pre = '' +url = "https://github.com/pixelfed/pixelfed" +weight = 30 +``` + +### frontmatter + +anything put in the docs menu will be available as in the big beefy menu section (which becomes a sidebar when the page is wide enough) + +```toml +title = "Generic installation guide" +summary = "How to set up everything you need to run your own Pixelfed instance." +weight = 20 +[menu] +[menu.docs] +identifier = "admin/installation" +parent = "admin" +``` \ No newline at end of file