Marupopo Documentation

website·Indexed 30 days ago

https://docs.marupopo.com

Technical guides and tutorials covering Docusaurus site deployment, GitHub Pages configuration, custom domain setup, and user manuals for Git and Shell.

Tokens: 10.4K
Snippets: 106
Records: 115
Agent score: 49%

What's inside Marupopo

Deploy Docusaurus to GitHub Pages using HTTPS and Personal Access Token (PAT)
If you do not have SSH configured, you can deploy using a GitHub Personal Access Token (PAT) with repo permissions. Update the remote URL to include the token, then run the deploy script.
```
# Set remote URL with PAT
git remote set-url origin https://<token>@github.com/Andromedasm/docusaurus-github.git

# Deploy the site
npm run deploy
```
https://docs.marupopo.com/docs/github-pages/step5/
Create a basic document in Docusaurus
To create a new document, create a Markdown file within the docs directory. For example, creating docs/hello.md will make the document available at the URL path /docs/hello.
```
# Hello

This is my **first Docusaurus document**!
```
https://docs.marupopo.com/docs/tutorial-basics/create-a-document/
Discard local changes to resolve git pull --rebase conflict
If local changes are unimportant and can be deleted, use git reset --hard to clear the working directory before pulling. Warning: This action permanently deletes all uncommitted changes.
```
git reset --hard
git pull origin gh-pages --rebase
```
https://docs.marupopo.com/docs/github-pages/step13/
Deploy Docusaurus to GitHub Pages using SSH
To use SSH for deployment instead of HTTPS, ensure your SSH key is added to your GitHub account and update your deployment script to use the USE_SSH=true flag.
```
# Verify SSH connection
ssh -T git@github.com
```
```
// package.json
"scripts": {
  "deploy": "USE_SSH=true docusaurus deploy"
}
```
```
# Deploy
npm run deploy
```
https://docs.marupopo.com/docs/github-pages/step4/
Create interactive blog posts using MDX
Blog posts support Docusaurus Markdown features, including MDX. This allows you to embed React components and use JSX directly within your blog content to create interactive elements.
```
<button onClick={() => alert('button clicked!')}>Click me!</button>
```
https://docs.marupopo.com/blog/mdx-blog-post/
Create and execute Bash shell scripts
To create a shell script, start the file with a shebang (#!/bin/bash). The script must be granted execute permissions using chmod +x before it can be run directly.
```
# Inside script.sh
#!/bin/bash
echo "This is a shell script"

# In the terminal
chmod +x script.sh
./script.sh
```
https://docs.marupopo.com/docs/linux/shell/
Translate a documentation page
To translate a document, copy the original markdown file from the docs directory into the corresponding locale folder within the i18n directory. The path follows the pattern: i18n/{locale}/docusaurus-plugin-content-docs/current/{filename}.
```
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
```
https://docs.marupopo.com/docs/tutorial-extras/translate-your-site/
Limit blog post content in list views using truncate
To prevent long blog posts from filling up the list view, use the  HTML comment. Content appearing before this comment will be shown in the list view summary, while content following it will be hidden until the full post is opened.
```
This text will appear in the blog list summary.



This text will only be visible on the full blog post page.
```
https://docs.marupopo.com/blog/long-blog-post/
Manage Docusaurus source code and gh-pages deployment branches
In a Docusaurus project, the gh-pages branch is reserved for static files (HTML, CSS, JS) generated by the build process and is used for hosting the site on GitHub Pages. Project source code, such as docusaurus.config.ts and Markdown files in the docs/ folder, must be managed in the source branch (typically main). To update the website, modify the source branch and run the deployment commands; do not modify the gh-pages branch directly.
```
# 1. Switch to source branch and update
git checkout main
git pull origin main

# 2. Make changes to docs or config, then build and deploy
npm run build
npm run deploy
```
https://docs.marupopo.com/docs/github-pages/step14/
Install Zsh on macOS and Ubuntu
Zsh can be installed using Homebrew on macOS or the APT package manager on Ubuntu.
```
# macOS
brew install zsh

# Ubuntu
sudo apt-get install zsh
```
https://docs.marupopo.com/docs/linux/shell/
Deploy Docusaurus to GitHub Pages using SSH
To deploy via SSH, verify your SSH connection to GitHub. Then, modify the deploy script in package.json to include the USE_SSH=true environment variable.
```
// package.json
"scripts": {
  "deploy": "USE_SSH=true docusaurus deploy"
}
```
```
# Verify SSH connection
ssh -T git@github.com

# Deploy the site
npm run deploy
```
https://docs.marupopo.com/docs/github-pages/step5/
Resolve Git conflicts between main and gh-pages branches
When Git reports unresolved conflicts between the gh-pages and main branches during a merge or pull operation, follow these steps to identify and resolve them manually.
```
# 1. Identify conflicting files
git status

# 2. After manually editing files to remove conflict markers (<<<<<<<, =======, >>>>>>>):
git add <file>

# 3. Complete the rebase or merge process
git rebase --continue
```
https://docs.marupopo.com/docs/github-pages/step15/