{"id":13622231,"url":"https://github.com/Enveloppe/mkdocs-publisher-template","last_synced_at":"2025-04-15T05:34:13.805Z","repository":{"id":37025010,"uuid":"442774216","full_name":"Enveloppe/mkdocs-publisher-template","owner":"Enveloppe","description":"The template for Obsidian Mkdocs Publisher, a free obsidian publish alternative throught Mkdocs.","archived":true,"fork":false,"pushed_at":"2024-02-25T00:45:33.000Z","size":31597,"stargazers_count":136,"open_issues_count":0,"forks_count":23,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-09-26T21:04:08.307Z","etag":null,"topics":["free","github-pages","markdown","material","material-mkdocs","mkdocs","mkdocs-material","obsidian","obsidian-md","publish","template"],"latest_commit_sha":null,"homepage":"https://obsidian-publisher.netlify.app/","language":"HTML","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Enveloppe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-29T13:01:41.000Z","updated_at":"2024-09-20T08:02:08.000Z","dependencies_parsed_at":"2023-02-18T01:16:16.378Z","dependency_job_id":"dc612ea4-2ee2-4d52-8491-ee40b07ac1c5","html_url":"https://github.com/Enveloppe/mkdocs-publisher-template","commit_stats":null,"previous_names":["obsidianpublisher/publisher-template-gh-pages","obsidianpublisher/mkdocs-template","obsidianpublisher/mkdocs-publisher-template","obsidianpublisher/template-gh-pages","enveloppe/mkdocs-publisher-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enveloppe%2Fmkdocs-publisher-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enveloppe%2Fmkdocs-publisher-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enveloppe%2Fmkdocs-publisher-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Enveloppe%2Fmkdocs-publisher-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Enveloppe","download_url":"https://codeload.github.com/Enveloppe/mkdocs-publisher-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223661472,"owners_count":17181675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["free","github-pages","markdown","material","material-mkdocs","mkdocs","mkdocs-material","obsidian","obsidian-md","publish","template"],"created_at":"2024-08-01T21:01:16.268Z","updated_at":"2024-11-08T09:31:13.153Z","avatar_url":"https://github.com/Enveloppe.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"---\ntitle: Configuration\n---\n\n- [Obsidian Plugin](https://github.com/ObsidianPublisher/obsidian-github-publisher)\n- [Template](https://github.com/ObsidianPublisher/mkdocs-publisher-template)\n- [Documentation](https://obsidian-publisher.netlify.app/)\n- [Github Discussion](https://github.com/ObsidianPublisher/obsidian-github-publisher/discussions)\n\n## Repository configuration\n\nThe repository and the template rely on [GitHub Actions](https://obsidian-publisher.netlify.app/template/actions/) to generate the website. You need to configure the repository to allow the actions to work properly.\n\n[Carefully follow this links to understand which keys you need to create](https://obsidian-publisher.netlify.app/template/actions/#secrets)\n\n\n## Mkdocs configuration\n\nYou need to configure the plugin and the `mkdocs` configuration for it to work properly.\n\nYou can find more information about creating the site using the [Material Mkdocs Documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration).\n\n\u003e [!Warning]\n\u003e Configuration is mandatory. Do not configure the template will lead to crash during build and errors.\n\nThere is two way to edit the template for creating the website :\n- Manually, with editing `mkdocs.yml` and creating appropriate workflows files,\n- Automatically, through a Github Action.\n\n### Automatic configuration\n\n1. First go into SETTINGS\n  - 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.\n  ![](https://i.imgur.com/VHPLooc.png)\n  - In `Actions` -\u003e `General` : Allow Github Actions to read and write, and allow GitHub Actions to create and approve pull requests, as follows:\n  ![](https://i.imgur.com/w79NrA8.png)\n  Don't forget to save the changes!\n  - Create a [personal access token](https://github.com/settings/tokens/new?description=PUBLISHER%20TEMPLATE\u0026scopes=repo,workflow), copy it and register it as a secrets :\n  ![](https://i.imgur.com/CW7YTms.png)\n  ![](https://i.imgur.com/9SCSooJ.png)\n  This key will also be used by the update workflows.\n  - If you choose to rely on netlify or vercel, [you need to configure the keys](https://obsidian-publisher.netlify.app/template/advanced_workflow/).\n2. Go into the Actions tabs\n3. Click on the Generate website workflow and `Run workflow`. A popup will appear, and fill the informations.\n  ![](https://i.imgur.com/QZj8bk0.png)\n  ![](https://i.imgur.com/n8wyvSp.png)\n  Each informations corresponding to the [mkdocs.yml configuration file](https://www.mkdocs.org/user-guide/configuration/).\n  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.\n  ![](https://i.imgur.com/SvPPyHc.png)\n4. Go into the pull-request tab. Verify all files, and if it's okay for you, you can merge the PR.\n  ![](https://i.imgur.com/zKtGagJ.png)\n\n### Manual configuration\n\n[The configuration of mkdocs.yml is explained here](https://www.mkdocs.org/user-guide/configuration/).\n\n1. First, edit the `mkdocs.yml` files with editing:\n- `site_name` : The name of your website\n- `site_description` : The description of your website\n- `site_author` : The author of your website\n- `site_url` : The url of your website\n- `language` : [The language of your website](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/)\n- In extra:\n    - `comments` : If you want to enable comments, you need to set it to `true` and [configure the comments](https://obsidian-publisher.netlify.app/advanced/customization/?h=comments#comments)\n    - `generate_graph` : Set it to `true` if **you use GitHub Pages** and you want to generate the graph view. Set it to `false` if you use Netlify or Vercel. [See here on how to configure the graph with Netlify/vercel](https://obsidian-publisher.netlify.app/template/advanced_workflow/)\n    - `auto_h1` : Disable the automatic generation of h1 if no h1 is found\n2. Create [keys if you use Vercel /Netlify](https://obsidian-publisher.netlify.app/template/advanced_workflow/).\n3. [Grab the `.env` and `deploy.yml` corresponding to your methods of deployment](https://github.com/ObsidianPublisher/actions/tree/main/template):\n    - `.env` must be placed at `.github/`\n    - `deploy.yml` must be placed at `.github/workflows/`\n4. For **Vercel** or **Netlify** ONLY, create a `requirements_actions.txt` file at the root of your repository, and add the following lines:\n    ```\n    obsidiantools==0.10.0\n    pyvis==0.3.1\n    ```\n5. **For Netlify ONLY** : Create a `runtime.txt` file with `3.8` in it.\n6. Create the [Github Personal Access Token](https://github.com/settings/tokens/new?description=PUBLISHER%20TEMPLATE\u0026scopes=repo,workflow) and register it as a secrets (see the automatic configuration for this).\n\n### Optional configuration\n\nTo edit the logo and favicon, first put the chosen files in the `assets/logo` directory, and then change `logo` and `favicon`:\n\n1. `logo: assets/meta/logo_name.png`\n2. `favicon: assets/meta/favicon.png`\n3. To properly work with SEO, also edit the `extra` with `SEO: 'assets/meta/LOGO_SEO.png'`\n\nYou can also customize:\n\n- Font\n- Color scheme, palette, and icons\n- Language\n\n[Check the documentation for more information](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/)\n\nYou don't need to touch anything in `features` or `markdown_extensions`.\n\n#### Extra configuration\n\nThe last part of the `mkdocs.yml` is a configuration for the `hooks` and the template Jinja displaying the list of articles (`blog_list.html`).\n\nThere are also :\n\n- `SEO` (_`string`_): Link to your default image displayed by the SEO.\n- `comments` (_`boolean`_) : Allow the comments block at the end of the page\n- `generate_graph` (_`boolean`_): Generate the [[customization#Graph view|graph view]]\n- `attachments` (_`boolean`_): For [[configuration#Blog list (article listing)]] and image in SEO. Change it according to your Obsidian Plugin settings.\n\n##### Blog list (article listing)\n\nThe list of articles is configured by the key `blog_list` and can take the following parameters :\n\n- `pagination` (_`boolean, default: True`_): Display a pagination if the list is too long.\n- `pagination_message` (_`boolean, default: True`_): Display a message with the number of posts (article/file) in the folder.\n- `pagination_translation` (`string, default: 'posts in'`): Translation of the pagination's message.\n- `no_page_found` (`string, default: \"No pages found!\"`): The text to display if no pages were found.\n\n##### Hooks\n\nThis part contains the configuration of `hooks`, short python scripts that allow to patch some Obsidian parts incompatible with Mkdocs.\n\nYou can configure :\n\n- The suppression of the Obsidian's comments (`%% comments %%`): `strip_comments: true`\n- 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`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEnveloppe%2Fmkdocs-publisher-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEnveloppe%2Fmkdocs-publisher-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEnveloppe%2Fmkdocs-publisher-template/lists"}