Personal feedback

[CYNAR2k]

Hello. First of all thanks for your work on this project. I'm not very skilled with code at all and I followed this guide step by step and somehow I managed to get it working after some good hours... I think there are some basic and maybe common sense steps missing here like for example telling that you have to need git command line software to make this work... You also didn't mention that you need to add "deploy": "gh-pages -d dist" on the package.json script to make the command "npm run deploy" work... This command also doesn't work if you don't have git installed. For some people this might be common sense, but for me it isn't... I had to take some hours to understand why this wasn't working at all.

Also, i had to use google translator in order to follow the rest of the steps since you only gave English instructions for the 1st page.

I would love if you would write a more noob/friendly user guide... Who knows even a youtube video tutorial explaining everything :)

I really like this project that converts markdown files into html websites.

Thank you!

[jaywcjlove]

https://wangchujiang.com/idoc/introduce/index.html

@CYNAR2k There are usage documents, but he is in Chinese.

[CYNAR2k]

@jaywcjlove i know the guide is there & in chinese but still i think the guide it's not that friendly user... For example i did a website using this, but i'm a little bit confused if i did it right or not.

https://github.com/CYNAR2k/link-z

Like, i only have gh-pages branch. Should the script also create some main branch where there is a README.md file? Or i have to do that manually?

[jaywcjlove]

You can place your source code on the main branch and use GitHub actions to compile and deploy it to the gh-pages branch."

.github/workflows/main.yml

```bash
name: npm
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          registry-url: 'https://registry.npmjs.org'

      - run: npm install
      - run: npm run doc
      - run: tree -I 'node_modules|.git|.github|src' -L 3 -a

      - name: Deploy Website
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

You can also manage a separate branch and commit the compiled static resources in the 'dist' folder to Git. In the Page settings, select the dist folder under the corresponding branch as the directory for static resources.

@CYNAR2k

[CYNAR2k]

I got the following error when i did the first step you told me:

Run npm run doc npm ERR! Missing script: "doc" npm ERR! npm ERR! Did you mean this? npm ERR! npm docs # Open documentation for a package in a web browser npm ERR! npm ERR! To see a list of scripts, run: npm ERR! npm run

npm ERR! A complete log of this run can be found in: npm ERR! /home/runner/.npm/_logs/2023-03-17T21_42_54_079Z-debug-0.log Error: Process completed with exit code 1.

And for some reason if i try the second method you told me to select dist it doesn't show up in the page settings. I only can select /root or /docs and i don't even have a folder called docs since i made the script run the static website from a readme.md located at the start of the folder (by this i mean, the readme.md it's not in any folder, just on the same spot where it's the package.json)

What am I doing wrong here?

EDIT: I missclicked and closed this, sorry, my bad.

[jaywcjlove]

https://github.com/jaywcjlove/idoc/blob/dc094cae044ed87f256bef17de65d8f8ec938fc8/package.json#L34

https://github.com/jaywcjlove/idoc/blob/dc094cae044ed87f256bef17de65d8f8ec938fc8/.github/workflows/ci.yml#L29

in the package.json file

  "scripts": {
    "start": "idoc -w",
+    "build": "idoc",
    "deploy": "gh-pages -d dist"
  },

In the .github/workflows/main.yml file

      - run: npm install
+     - run: npm run build

@CYNAR2k

[CYNAR2k]

Okay that worked finally! I still think that your guide it's confusing, it would be awesome if you had time to re-make it & turn it into friendly user :)

Also if you wanna check my repo https://github.com/CYNAR2k/link-z just to see if I actually did everything correctly would be awesome 👍

I also have a small "problem" on my website, you can understand it easy by just opening it and click on the badges that work as a table of contents. When you click on them, they will go to the topic but the top bar from the website stays on the top of the title of that topic. Is there a way to make the bar stop above the topic title? https://imgur.com/a/B1OH3Nn

Thanks again for this cool script!

[jaywcjlove]

@CYNAR2k I didn't understand what you mean, I guess it might be the following solution:

[Back Top](#quick-start)<!--rehype:class=anchor&aria-hidden=true&style=float:initial;margin-left: 0;-->

[CYNAR2k]

When I click on the topics menu, for example "Benchmark & Performance Tools" it scrolls down to Benchmark & Performance Tools, but the top bar hides the title "Benchmark & Performance Tools". Heres the example: https://imgur.com/a/B1OH3Nn Is there a way to make it pause above the title? Example of what i want: https://imgur.com/a/ZEim5kw

[jaywcjlove]

@CYNAR2k Do you want to remove the fixed header?

[CYNAR2k]

@jaywcjlove No. Currently this is what happens when i click on "Benchmark & Performance Tools" https://imgur.com/a/B1OH3Nn And i want that when i click it it stops a little bit before the title like this : https://imgur.com/a/ZEim5kw

[jaywcjlove]

https://user-images.githubusercontent.com/1680273/226497068-3cddecb3-5e7c-4e22-9ba3-d66af0f2d8eb.mp4

@CYNAR2k

[jaywcjlove]

https://user-images.githubusercontent.com/1680273/226497317-1f2c06f4-ee86-465b-843f-cdb7117ca211.mp4

[CYNAR2k]

Well yeah I know you can do that, but if you click on this buttons see what happens...

[jaywcjlove]

@CYNAR2k I have already given you the answer. You only need to add class=anchor, aria-hidden=true to the generated <a> hyperlink.

Write html comment mark in markdown:

<a href="#xxx">xxx</a><!--rehype:class=anchor&aria-hidden=true&style=float:initial;margin-left: 0;--> 

Comment markup for markdown syntax:

[Back Top](#quick-start)<!--rehype:class=anchor&aria-hidden=true&style=float:initial;margin-left: 0;-->

[jaywcjlove]

@CYNAR2k

<p align="center"> 
  <a href="#guides-"><img src="https://img.shields.io/badge/%F0%9F%93%9A%20-Guides-blue?style=for-the-badge"/></a><!--rehype:class=anchor&aria-hidden=true&style=float:initial;padding-right: 0;margin-left: 0;-->  
  <a href="#windows-"><img src="https://img.shields.io/badge/%F0%9F%AA%9F-%20Windows%20-blue?style=for-the-badge"/></a><!--rehype:class=anchor&aria-hidden=true&style=float:initial;padding-right: 0;margin-left: 0;-->  
  <a href="#software-"><img src="https://img.shields.io/badge/%F0%9F%94%A7-Software%20-blue?style=for-the-badge"/></a><!--rehype:class=anchor&aria-hidden=true&style=float:initial;padding-right: 0;margin-left: 0;-->  
  <a href="#benchmark--performance-tools-"><img src="https://img.shields.io/badge/%F0%9F%92%BB-Benchmark%20%26%20Performance%20Tools%20-blue?style=for-the-badge"/></a><!--rehype:class=anchor&aria-hidden=true&style=float:initial;padding-right: 0;margin-left: 0;-->  
  <a href="#reviews-"><img src="https://img.shields.io/badge/%F0%9F%94%8E-Reviews-blue?style=for-the-badge"/></a><!--rehype:class=anchor&aria-hidden=true&style=float:initial;padding-right: 0;margin-left: 0;-->  
  <a href="#websites-"><img src="https://img.shields.io/badge/%F0%9F%8C%90-Websites-blue?style=for-the-badge"/></a><!--rehype:class=anchor&aria-hidden=true&style=float:initial;padding-right: 0;margin-left: 0;-->  
</p>

[CYNAR2k]

@jaywcjlove Yup, problem solved. Thank you a lot for your help & once again thanks for this amazing script! The pages that github creates by default should look like the ones idoc creates, idoc default ones are just perfect! Thank you!!! :D