Common workflows for modifying Astrolock

Making Changes

Common modification workflows for Astrolock development.

Warning

Always test changes with make test before committing. See Testing.

Changing Styles

Files: src/styles/global.css, src/styles/variables.css, tailwind.config.cjs

# Edit styles
vim src/styles/global.css

# Test with dev server
yarn dev
# Visit http://localhost:4321

Files: src/layouts/partials/*.astro, src/components/*.astro

Find the component, edit inline styles or Tailwind classes, test with yarn dev.

Adding Components

MDX Shortcode
Astro Component

Create reusable components for MDX content.

# Create component
cat > src/layouts/shortcodes/MyComponent.tsx << 'EOF'
interface Props {
  title: string;
  type?: 'info' | 'warning';
}

export default function MyComponent({ title, type = 'info' }: Props) {
  return (
    <div className={`my-component--${type}`}>
      <h3>{title}</h3>
    </div>
  );
}
EOF

# Use in MDX
# <MyComponent title="Hello" type="warning" />

# Test
yarn dev

Create layout components.

# Create component
cat > src/components/MyWidget.astro << 'EOF'
---
interface Props {
  title: string;
}
const { title } = Astro.props;
---
<div class="my-widget">
  <h2>{title}</h2>
</div>
EOF

# Import and use
# ---
# import MyWidget from '@/components/MyWidget.astro';
# ---
# <MyWidget title="Test" />

Modifying the CLI

Add Command
Modify Existing
Add Shared Functions

Edit cli/bashly.yml

commands:
  - name: mycommand
    help: Description
    args:
      - name: input
        required: true
    flags:
      - long: --verbose
        short: -v

Create cli/commands/mycommand.sh

input="${args[input]}"
verbose="${args[--verbose]}"

echo "Processing: $input"

Regenerate and test

bashly generate
./bin/astrolock mycommand "test" --verbose

Adding Features to Content Collections

Update schema: src/content.config.ts

const audioSchema = z.object({
  // existing fields...
  myNewField: z.string().optional(),
});

Use in templates

---
const { myNewField } = Astro.props.entry.data;
---
{myNewField && <p>{myNewField}</p>}

Document: Update src/content/user-guide/reference/frontmatter/*.mdx

Add to config schema: src/lib/config/unified-config-schema.ts

features: {
  myFeature: z.boolean().optional(),
}

Use in templates

---
const config = await loadUnifiedConfig();
const hasFeature = config.collections?.[collection]?.features?.myFeature;
---
{hasFeature && <MyFeatureComponent />}

Document: Update src/content/user-guide/reference/*.mdx

Adding Import Plugins

Create plugin folder: mkdir -p plugins/my-plugin
Add plugin code: plugins/my-plugin/myPlugin.ts
Add CLI command in cli/bashly.yml:

- name: my-plugin
  help: Import from my-plugin
  args:
    - name: input
      required: true

Create command: cli/commands/import/my-plugin.sh

input="${args[input]}"
node plugins/my-plugin/myPlugin.js "$input"

Test:

bashly generate
./bin/astrolock import my-plugin /path/to/input

Contributing Guidelines

When contributing to Astrolock:

Fork and clone the repository
Create feature branch from main
Make changes following existing patterns
Run tests with make test
Submit pull request with clear description

Code Style

Use yarn not npm
Use make targets for builds
Follow existing file organization
Add tests for new features
Update documentation

Testing Requirements

# All tests must pass
make test

# Test in a user site
cd ~/test-site
/path/to/astrolock-template/bin/astrolock build

Reporting Issues

Open issues at github.com/eyelock/astrolock-template/issues with:

OS and versions (Node.js, Yarn, OS)
Steps to reproduce
Error messages
Expected vs actual behavior

Tip

Need detailed reference? See Architecture and Directory Structure.