Git Product home page Git Product logo

amethyst's Introduction

Amethyst Hugo Theme

Hugo License: MIT

amethyst screenshot

Why Amethyst?

I write most of my notes in Obsidian. When trying to find a suitable open-source alternative for Obsidian Publish, I couldn't find exactly what I was looking for: a simple, customizable theme with sidebar navigation that supported Obsidian features (like backlinks or LaTeX) in such a way that didn't require me to reformat my notes.

Amethyst is an attempt to deliver this by combining the navigational features of hugo-book with the Obsidian integrations of quartz to provide a hassle-free place to store and host personal notes or documentation.

Features

Amethyst preserves most of the features of quartz and hugo-book, including:

  • Navigation sidebars on left and right of content
  • Obsidian-style callouts
  • Interactive graph view
  • MermaidJS charts
  • User-togglable dark mode
  • Search bar
  • Multi-language support
  • Mobile support
  • Obsidian-style back/forward links and page previews

Some new features that were added on top:

  • Custom formatting of tabs, sections, and expands specifically for Q&A-style interaction
  • Easy customization of theme colors and fonts
  • LaTeX enabled out of the box with no additional config
  • Support for both absolute and relative links, Obsidian-style

Documentation

If you just want to use Amethyst for your own notes hosting, go to amethyst.bencuan.me for a demo and documentation on how to use it.

Keep reading if you want to help develop Amethyst, or make changes to the code base for your own needs.

Requirements

Live Server

Start the live server using make serve. Content will be served to localhost:1313 by default.

The server will need to be restarted to preview changes to navigation (internal links and sidebar menu).

Configuration

Site Configuration

Most configuration can be done by creating a config.yaml file in the root directory and editing the parameters. You can start by copying the example here.

Graph-specific configuration can be added to data/graphConfig.yaml. (Example here)

Multi-Language Support

Theme supports Hugo's multilingual mode, just follow configuration guide there. You can also tweak search indexing configuration per language in i18n folder.

Page Configuration

You can specify additional params in the front matter of individual pages:

# Set type to 'docs' if you want to render page outside of configured section or if you render section other than 'docs'
type = 'docs'

# Set page weight to re-arrange items in file-tree menu (if BookMenuBundle not set)
weight = 10

# (Optional) Set to 'true' to mark page as flat section in file-tree menu (if BookMenuBundle not set)
bookFlatSection = false

# (Optional) Set to hide nested sections or pages at that level. Works only with file-tree menu mode
bookCollapseSection = true

# (Optional) Set true to hide page or section from side menu (if BookMenuBundle not set)
bookHidden = false

# (Optional) Set 'false' to hide ToC from page
bookToC = true

# (Optional) If you have enabled BookComments for the site, you can disable it for specific pages.
bookComments = true

# (Optional) Set to 'false' to exclude page from search index.
bookSearchExclude = true

# (Optional) Set explicit href attribute for this page in a menu (if BookMenuBundle not set)
bookHref = ''

Partials

There are layout partials available for you to easily override components of the theme in layouts/partials/.

In addition to this, there are several empty partials you can override to easily add/inject code.

Empty Partial Placement
layouts/partials/docs/inject/head.html Before closing <head> tag
layouts/partials/docs/inject/body.html Before closing <body> tag
layouts/partials/docs/inject/footer.html After page footer content
layouts/partials/docs/inject/menu-before.html At the beginning of <nav> menu block
layouts/partials/docs/inject/menu-after.html At the end of <nav> menu block
layouts/partials/docs/inject/content-before.html Before page content
layouts/partials/docs/inject/content-after.html After page content
layouts/partials/docs/inject/toc-before.html At the beginning of table of contents block
layouts/partials/docs/inject/toc-after.html At the end of table of contents block

Extra Customisation

File Description
static/favicon.png Override default favicon
assets/_custom.scss Customise or override scss styles
assets/_variables.scss Override default SCSS variables
assets/_fonts.scss Replace default font with custom fonts (e.g. local files or remote like google fonts)
assets/_colors.scss Change the default color schemes
assets/mermaid.json Replace Mermaid initialization config

Plugins

There are a few features implemented as plugable scss styles. Usually these are features that don't make it to the core but can still be useful.

Plugin Description
assets/plugins/_numbered.scss Makes headings in markdown numbered, e.g. 1.1, 1.2
assets/plugins/_scrollbars.scss Overrides scrollbar styles to look similar across platforms

To enable plugins, add @import "plugins/{name}"; to assets/_custom.scss in your website root.

Hugo Internal Templates

There are a few hugo templates inserted in <head>

To disable Open Graph inclusion you can create your own empty file \layouts\_internal\opengraph.html. In fact almost empty not quite empty because an empty file looks like absent for HUGO. For example:

<!-- -->

Versioning

This theme follows a simple incremental versioning. e.g. v1, v2 and so on. There might be breaking changes between versions.

If you want lower maintenance, use one of the released versions. If you want to live on the bleeding edge of changes, you can use the main branch and update your website when needed.

Contributing

Contributions are welcome! Please make an issue or pull request if there are any changes you'd like to see.

Credits

A large portion of Amethyst's code base can be derived from the following two projects. Original attribution goes to the creators of these projects; I just put them together, squashed all the bugs, and customized the styles to fit my needs for Amethyst.

amethyst's People

Contributors

64bitpandas avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

amethyst's Issues

A Chinese tutorial is required.

Is your feature request related to a problem? Please describe.

Hello, I like your theme very much. Can you give a Chinese tutorial when you have time?

Describe the solution you'd like
...

Describe alternatives you've considered
...

Additional context
...

Having a deployment bug

Describe the bug
A clear and concise description of what the bug is.
I chage all step of the workflow and push the code but the deployment is show me the error about the Jekyll.?
I don't want to use Jekyll that is why I use Hugo. but the deployment code is not show the Jekyll but the rendering is show me the layout of the error of Jekyll.

Can you help me ?

To Reproduce
Steps to reproduce the behavior:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Build Link Index
        uses: jackyzha0/[email protected]
        with:
          index: true
          input: content
          output: assets/indices
          root: .

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.96.0'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: deploy  # deploying branch
          cname: voidmain443.github.io

Expected behavior
it have to be publish but it is doesn't.

Screenshots
If applicable, add screenshots to help explain your problem.
image

it is different here that the Jekyll is not on the official docs .

image

image

Desktop (please complete the following information):

  • Device: GitHub workflow
  • OS: Mac GitHub workflow
  • Browser [e.g. chrome, safari]

Additional context
Add any other context about the problem here.

Unable to display Backlinks

I am encountering an issue where I am unable to display Backlinks on my website. The Backlinks feature is not functioning as expected, and I have followed the necessary steps to set it up correctly.

Steps to Reproduce:

go install github.com/jackyzha0/hugo-obsidian@latest
make serve

output

[DONE] in 31ms
Ignored 0 private files
Parsed 78 total links
Removed 47 external and non-markdown links
hugo server --enableGitInfo --minify --bind=0.0.0.0 --baseURL=http://localhost --port=1313 --appendPort=true

Expected Behavior:
The page should display the list of Backlinks, showing the other pages that link to it.

Actual Behavior:
The page does not display any Backlinks even though there are other pages linking to it.

Additional Information:
The link format I am using is:
1.[A link to the config page](setup/config.md)
2.[[example/collapsed/3rd-level/4th-level|4th-level]](The link automatically inserted by Obsidian after inputting "[[" οΌ‰

How can I enable the menubar to see file tree

I'm a noob who read all the files but cannot figure out how to fix it...
Sorry for disturbing.
Windows plat form. I use obsidian to manage my notes.

This is my config.yaml file:

baseURL: https://amethyst.bencuan.me

bookFlatSection: false

# Book configuration
disablePathToLower: true
enableGitInfo: false

# # Needed for mermaid/katex shortcodes
markup:
  goldmark:
    renderer:
      unsafe: true
  tableOfContents:
    startLevel: 1

# Multi-lingual mode config
# There are different options to translate files
# See https://gohugo.io/content-management/multilingual/#translation-by-filename
# And https://gohugo.io/content-management/multilingual/#translation-by-content-directory

# Sidebar menu additional links
menu:
  before:
    - name: "Sample"
      url: "https://google.com"
      weight: 10
  after:
    - name: "Github"
      url: "https://github.com/64bitpandas/amethyst"
      weight: 10

params:

  name: 10k
  title: 10k's Digital Garden

  # OPTIONAL: custom favicon location
  # favicon: 'location/to/favicon.png'

  # whether to display on-hover link preview cards
  enableLinkPreview: false

  # Enable rendering of LaTeX blocks
  # (surrounded by either single or double dollar signs)
  enableLatex: true

  # whether to render titles for code blocks
  enableCodeBlockTitle: true

  # whether to render copy buttons for code blocks
  enableCodeBlockCopy: true

  # whether to render callouts
  enableCallouts: true

  # Show footer, including backlinks and graph view
  enableFooter: true

  # whether backlinks of pages should show the context in which
  # they were mentioned
  enableContextualBacklinks: true

  # whether to show a section of recent notes on the home page
  enableRecentNotes: true
  
  # whether to display an 'edit' button next to the last edited field
  # that links to github
  enableGitHubEdit: false

  # whether to render mermaid diagrams
  enableMermaid: true

  # Link to your Github repo
  GitHubLink: https://tenthousand.cn
	# https://github.com/64bitpandas/amethyst

  # Search (WIP)
  search:
    enableSemanticSearch: true
    operandApiKey: "REPLACE-WITH-YOUR-OPERAND-API-KEY"
    operandIndexId: "REPLACE-WITH-YOUR-OPERAND-INDEX-ID"

  # Site description and title
  description:
    Notes, hosted by me

  
  # Footer links
  links:
    - link_name: Website
      link: https://bencuan.me
    - link_name: Blog
      link: https://blog.bencuan.me

  # (Optional, default true) Controls table of contents visibility on right side of pages.
  # Start and end levels can be controlled with markup.tableOfContents setting.
  # You can also specify this parameter per page in front matter.
  BookToC: true

  # (Optional, default none) Set the path to a logo for the book. If the logo is
  # /static/logo.png then the path would be logo.png
  BookLogo: /logo.png

  # (Optional, default none) Set leaf bundle to render as side menu
  # When not specified file structure and weights will be used
  BookMenuBundle: "/"

  # (Optional, default docs) Specify root page to render child pages as menu.
  # Page is resoled by .GetPage function: https://gohugo.io/functions/getpage/
  # For backward compatibility you can set '*' to render all sections to menu. Acts same as '/'
  BookSection: "/"

  # Set source repository location.
  # Used for 'Last Modified' and 'Edit this page' links.
  BookRepo: https://github.com/64bitpandas/amethyst

  # (Optional, default 'commit') Specifies commit portion of the link to the page's last modified
  # commit hash for 'doc' page type.
  # Requires 'BookRepo' param.
  # Value used to construct a URL consisting of BookRepo/BookCommitPath/<commit-hash>
  # Github uses 'commit', Bitbucket uses 'commits'
  BookCommitPath: commit

  # Enable "Edit this page" links for 'doc' page type.
  # Disabled by default. Uncomment to enable. Requires 'BookRepo' param.
  # Edit path must point to root directory of repo.
  BookEditPath: edit/main/exampleSite

  # Configure the date format used on the pages
  # - In git information
  # - In blog posts
  BookDateFormat: "January 2, 2006"


  # (Optional, default true) Enables comments template on pages
  # By default partals/docs/comments.html includes Disqus template
  # See https://gohugo.io/content-management/comments/#configure-disqus
  # Can be overwritten by same param in page frontmatter
  BookComments: true

  # /!\ This is an experimental feature, might be removed or changed at any time
  # (Optional, experimental, default false) Enables a drop-down menu for translations only if a translation is present.
  BookTranslatedOnly: false

  # Don't change this
  enableSPA: false
  BookSearch: false
  BookServiceWorker: false
  BookPortableLinks: false

added:
bookFlatSection: false

Themes Header is completly broken when loaded into Hugo

Describe the bug
The header is broken with both the searchbar being completly missplaced and the title being out of place ass well. The fonts are also wrong and the switch for Dark/Light theme are completly gone.

To Reproduce
Steps to reproduce the behavior:

  1. Git clone https://github.com/64bitpandas/amethyst ./themes
  2. Set "theme = "amethyst" " in config.toml
  3. Use "cp ./themes/amethyst/assets ./assets" to copy the themes assets folder into the working assets folder. I got several error messages if I didn't.
  4. "hugo serve"

Expected behavior
I'd expect the header to look as per the demo. The search bar to the right and the text in it's proper place. Check the demo for a ...well... demo of how it should look.

Screenshots
Imgur links to show what doesn't work.

Desktop (please complete the following information):

  • Device: Unraid VM
  • OS: Ubuntu Server 22.04
  • Browser: Vivaldi
  • Hugo version: 0.125.3+extended (installed from snap)
  • Node.js: v21.7.3
  • Node: 20.12.2

Additional context
A little question, why must the "assets" folder be copied into the root dir for the site? I thought themes fetched their assets from their respective themes/{theme-name} folder?

How to upgrade to quartz 4? (make update doesn't work)

Is your feature request related to a problem? Please describe.
I would like to be able to upgrade to quartz v4 as there's a bug in styling that's fixed in the latest version

Describe the solution you'd like
Understand how to upgrade the version of quartz in this project/theme. It's not entirely clear since the only two folders I see under "assets/quartz" are "js" and "styles"

Describe alternatives you've considered
None

Additional context
I'm just looking for a way to get my head wrapped around how Quartz is used here. If there was a way that I could do the upgrade and post a PR, I'd do the honors. But the mismatch between what I see in the structure here and the full quartz repo gives me pause.

Cannot get theme modifications to render (color changes)

Describe the bug
I'm looking to get a templated version of the Amethyst theme to "change colors". I've both changed the colors.scss and custom.scss and haven't seen anything shift. I've tried the noted flags such as hugo server --disableFastRender in order to get "full rebuilds".

Expected behavior
Site color scheme changes with modification of either colors.scss or custom.scss

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

  • Device: Laptop
  • OS: Win11
  • Browser: Chrome

Additional context
Just for "laughs" I used the following colors just to see something different

:root {
    --light: #faf8f8;
    --dark: #141021;
    --secondary: #d98d00; /* Orange tone for secondary */
    --tertiary: #ff9148; /* Orange tone for tertiary */
    --visited: #d97c00; /* Orange tone for visited */
    --primary: #ff825c; /* Main orange color for primary */
    --gray: #3f3f3f;
    --lightgray: #f0f0f0;
    --outlinegray: #dadada;
    --million-progress-bar-color: var(--secondary);
    --highlighted: #ffbf8e; /* Lighter orange tone for highlighted */
    --header: #fdaa7b; /* Orange tone for header */
    --title: rgb(232, 139, 79); /* Orange tone for title */
    --scrollbar: gray;
    --scrollbar-track: #DDD;
}

[saved-theme="dark"] {
    --light: #1e1e21 !important;
    --dark: #f7f2fa !important;
    --secondary: #e7a100 !important; /* Orange tone for secondary */
    --visited: #e19600 !important; /* Orange tone for visited */
    --tertiary: #b28a00 !important; /* Orange tone for tertiary */
    --primary: #f58382 !important; /* Retained the original primary color */
    --gray: #d4d4d4 !important;
    --lightgray: #292633 !important;
    --outlinegray: #343434 !important;
    --highlighted: #574010;
    --header: #38c8f8;
    --title: rgba(250, 153, 8, 0.881);
    --scrollbar: rgb(177, 177, 177);
    --scrollbar-track: rgb(51, 51, 51);
}

and here's the output of my console when I run the command

PS C:\repos\fsharpnotes> make serve -B
hugo-obsidian -input=content -output=assets/indices -index -root=.
Scraping content
[Parsing note] /_index => found: 16 links
[Parsing note] /example/_index => found: 4 links
[Parsing note] /example/collapsed/3rd-level/4th-level => found: 1 links
[Parsing note] /example/collapsed/3rd-level/_index => found: 0 links
[Parsing note] /example/collapsed/_index => found: 0 links
[Parsing note] /example/hidden => found: 2 links
[Parsing note] /example/table-of-contents/_index => found: 3 links
[Parsing note] /example/table-of-contents/with-toc => found: 6 links
[Parsing note] /example/table-of-contents/without-toc => found: 1 links
[Parsing note] /features/_index => found: 0 links
[Parsing note] /features/buttons => found: 0 links
[Parsing note] /features/callouts => found: 1 links
[Parsing note] /features/columns => found: 0 links
[Parsing note] /features/details => found: 0 links
[Parsing note] /features/expand => found: 0 links
[Parsing note] /features/languages => found: 1 links
[Parsing note] /features/latex => found: 0 links
[Parsing note] /features/mermaid => found: 2 links
[Parsing note] /features/section/_index => found: 0 links
[Parsing note] /features/section/first-page => found: 0 links
[Parsing note] /features/section/second-page => found: 0 links
[Parsing note] /features/tabs => found: 0 links
[Parsing note] /setup/_index => found: 0 links
[Parsing note] /setup/config => found: 8 links
[Parsing note] /setup/custom Domain => found: 1 links
[Parsing note] /setup/editing => found: 7 links
[Parsing note] /setup/hosting => found: 6 links
[Parsing note] /setup/ignore notes => found: 1 links
[Parsing note] /setup/obsidian => found: 3 links
[Parsing note] /setup/preview changes => found: 3 links
[Parsing note] /setup/search => found: 1 links
[Parsing note] /setup/setup => found: 6 links
[Parsing note] /setup/troubleshooting => found: 11 links
[Parsing note] /setup/updating => found: 0 links
[DONE] in 20ms
Ignored 0 private files
Parsed 84 total links
Removed 50 external and non-markdown links
hugo server --enableGitInfo --minify --bind=0.0.0.0 --baseURL=http://localhost --port=1313 --appendPort=true
Watching for changes in C:\repos\fsharpnotes\{archetypes,assets,content,data,i18n,layouts,static}
Watching for config changes in C:\repos\fsharpnotes\config.yaml, C:\repos\fsharpnotes\go.mod
Start building sites …
hugo v0.116.1-3e1ea030a5897addaf9d113d0826709fe07f77c0 windows/amd64 BuildDate=2023-08-01T07:24:54Z VendorInfo=gohugoio

WARN  Expand shortcode is deprecated. Use 'details' instead.

                   | EN
-------------------+-----
  Pages            | 49
  Paginator pages  |  0
  Non-page files   |  4
  Static files     | 79
  Processed images |  0
  Aliases          |  5
  Sitemaps         |  1
  Cleaned          |  0

Built in 188 ms
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 0.0.0.0)
Press Ctrl+C to stop

A page view feature

Is your feature request related to a problem? Please describe.
Need a way to display page view counts for each screen and the blog itself

If this not supported by default, I have html code that do this, where I can use it.

Backlinks preview similar to little-ocean theme

Hello,

first I would like to thank you for this wonderful Amethyst Theme.

Nevertheless, I think that the little-ocean theme (https://github.com/justindsmith/little-ocean) offer better backlink preview. Please, see this page : https://little-ocean.netlify.app/list-of-characters/ and see the preview of the "Luke Skywalker" link. You'll see that text and image are displayed. I don't think this is the case for Amethyst backlinks preview.

Unfortunately, I don't have the skill to try to implement the necessary code (html layout, css and js script) to obtain the same result with Amethyst. Could you examine the little-ocean code in order to see if it's possible to reproduce the backlink preview in Amethyst. Also please notice that the little-ocean theme doesn't need to run any external tool (i.e. hugo-obsidian) in order to generate backlinks and I wonder how this is done.. (Of course I understand that hugo-obsidian is mandatory in order to generate the knowledge graph beautifully displayed by Amethyst.

Thank you in advance for your help on this topic.

Phil.B

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.