Giter Site home page Giter Site logo

obsidianpublisher / mkdocs-publisher-template Goto Github PK

View Code? Open in Web Editor NEW
135.0 2.0 25.0 30.86 MB

The template for Obsidian Mkdocs Publisher, a free obsidian publish alternative throught Mkdocs.

Home Page: https://obsidian-publisher.netlify.app/

License: GNU Affero General Public License v3.0

HTML 53.22% Python 46.78%
obsidian-md publish free mkdocs material-mkdocs template markdown material mkdocs-material obsidian

mkdocs-publisher-template's Introduction

title
Configuration

Repository configuration

The repository and the template rely on GitHub Actions to generate the website. You need to configure the repository to allow the actions to work properly.

Carefully follow this links to understand which keys you need to create

Mkdocs configuration

You need to configure the plugin and the mkdocs configuration for it to work properly.

You can find more information about creating the site using the Material Mkdocs Documentation.

Warning

Configuration is mandatory. Do not configure the template will lead to crash during build and errors.

There is two way to edit the template for creating the website :

  • Manually, with editing mkdocs.yml and creating appropriate workflows files,
  • Automatically, through a Github Action.

Automatic configuration

  1. First go into SETTINGS
  • In Pages : If you want to use the template with Github Pages, you need to activate the GitHub Pages in your repository settings, and use action to trigger the page build.
  • In Actions -> General : Allow Github Actions to read and write, and allow GitHub Actions to create and approve pull requests, as follows: Don't forget to save the changes!
  • Create a personal access token, copy it and register it as a secrets : This key will also be used by the update workflows.
  • If you choose to rely on netlify or vercel, you need to configure the keys.
  1. Go into the Actions tabs
  2. Click on the Generate website workflow and Run workflow. A popup will appear, and fill the informations. Each informations corresponding to the mkdocs.yml configuration file. By default, the workflows will send you a pull requests, so you can review the generation before the merging. You can automatically merge with the last options.
  3. Go into the pull-request tab. Verify all files, and if it's okay for you, you can merge the PR.

Manual configuration

The configuration of mkdocs.yml is explained here.

  1. First, edit the mkdocs.yml files with editing:
  • site_name : The name of your website
  • site_description : The description of your website
  • site_author : The author of your website
  • site_url : The url of your website
  • language : The language of your website
  • In extra:
  1. Create keys if you use Vercel /Netlify.
  2. Grab the .env and deploy.yml corresponding to your methods of deployment:
    • .env must be placed at .github/
    • deploy.yml must be placed at .github/workflows/
  3. For Vercel or Netlify ONLY, create a requirements_actions.txt file at the root of your repository, and add the following lines:
    obsidiantools==0.10.0
    pyvis==0.3.1
    
  4. For Netlify ONLY : Create a runtime.txt file with 3.8 in it.
  5. Create the Github Personal Access Token and register it as a secrets (see the automatic configuration for this).

Optional configuration

To edit the logo and favicon, first put the chosen files in the assets/logo directory, and then change logo and favicon:

  1. logo: assets/meta/logo_name.png
  2. favicon: assets/meta/favicon.png
  3. To properly work with SEO, also edit the extra with SEO: 'assets/meta/LOGO_SEO.png'

You can also customize:

  • Font
  • Color scheme, palette, and icons
  • Language

Check the documentation for more information

You don't need to touch anything in features or markdown_extensions.

Extra configuration

The last part of the mkdocs.yml is a configuration for the hooks and the template Jinja displaying the list of articles (blog_list.html).

There are also :

  • SEO (string): Link to your default image displayed by the SEO.
  • comments (boolean) : Allow the comments block at the end of the page
  • generate_graph (boolean): Generate the [[customization#Graph view|graph view]]
  • attachments (boolean): For [[configuration#Blog list (article listing)]] and image in SEO. Change it according to your Obsidian Plugin settings.
Blog list (article listing)

The list of articles is configured by the key blog_list and can take the following parameters :

  • pagination (boolean, default: True): Display a pagination if the list is too long.
  • pagination_message (boolean, default: True): Display a message with the number of posts (article/file) in the folder.
  • pagination_translation (string, default: 'posts in'): Translation of the pagination's message.
  • no_page_found (string, default: "No pages found!"): The text to display if no pages were found.
Hooks

This part contains the configuration of hooks, short python scripts that allow to patch some Obsidian parts incompatible with Mkdocs.

You can configure :

  • The suppression of the Obsidian's comments (%% comments %%): strip_comments: true
  • A fix for headings, which adds a # to all headings (except the 6th one) because the Mkdocs TOC considers that the H1 is the main heading/title of the file: fix_heading: true

mkdocs-publisher-template's People

Contributors

github-actions[bot] avatar hannesdelbeke avatar janc-pxl avatar lisandra-dev avatar mearman avatar northword avatar prcr avatar sanderdatema 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

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.