Getting started overview

Getting started with Changelogs.md involves creating an account, setting up a new project, and publishing your initial changelog entry. The process supports both direct interaction through the web dashboard and programmatic access via API for publishing updates. The platform is designed to centralize release notes and product updates for developers and technical buyers (Changelogs.md official documentation). This guide outlines the steps to get a project operational and make a first post.

The core functionality of Changelogs.md centers on managing and displaying updates. Users can create posts with markdown support, categorize them, and publish them to a dedicated changelog feed. Integration options include embeddable widgets for existing websites or applications (Changelogs.md embedding guides).

Here's a quick reference table for the initial setup steps:

Step What to do Where
1. Sign Up Create a new Changelogs.md account. Changelogs.md signup page
2. Create Project Set up your first changelog project. Changelogs.md dashboard
3. Retrieve API Key (Optional) Generate or find your API key for programmatic access. Project Settings > API Keys
4. Publish Entry Create and publish your first changelog post. Web dashboard or API endpoint

Create an account and get keys

To begin using Changelogs.md, register for a new account. The platform offers a Developer Plan that includes one project and one editor, suitable for initial exploration and small-scale use. Account creation typically involves providing an email address and setting a password.

  1. Navigate to the Signup Page: Go to the official Changelogs.md signup portal.
  2. Provide Details: Enter your email address, create a strong password, and agree to the terms of service.
  3. Verify Email: You may receive an email verification link. Click the link to activate your account.
  4. Access Dashboard: Upon successful signup and verification, you will be redirected to your Changelogs.md dashboard.

Once logged in, you can create your first project. A project in Changelogs.md represents a distinct product or service for which you want to publish updates. Each project has its own dedicated changelog feed.

  1. Create a New Project: From the dashboard, locate the option to create a new project. You will typically be prompted to provide a project name and a unique slug.
  2. Configure Project Settings: After creating the project, navigate to its settings. Here you can customize display options, integrate widgets, and manage access.

For programmatic interaction, Changelogs.md provides API keys. These keys authenticate your requests when publishing or managing changelog entries outside the web interface. API keys are generated and managed within each project's settings.

  1. Locate API Keys: Within your project settings, find the section labeled "API Keys" or "Integrations."
  2. Generate Key: If a key isn't already present, generate a new API key. Ensure you copy and store this key securely, as it may only be shown once for security reasons.
  3. Understand Permissions: Be aware of the permissions associated with your API key. Some keys might have read-only access, while others allow for publishing and editing.

Managing API keys securely is a standard practice across many API providers to prevent unauthorized access to resources. For example, Stripe's documentation on API keys emphasizes the importance of protecting secret keys and using different keys for different environments.

Your first request

After setting up your account and project, you can publish your first changelog entry. This can be done through the Changelogs.md web interface or by using the API.

Using the Web Interface

The web interface offers a direct method for creating and publishing updates without writing any code.

  1. Navigate to Your Project: From the Changelogs.md dashboard, select the project you wish to update.
  2. Create a New Post: Look for a "New Post" or "Add Entry" button.
  3. Compose Your Post:
    • Title: Provide a concise title for your update (e.g., "New Feature: Dark Mode").
    • Content: Write the details of your update using Markdown. Markdown allows for formatting text, adding links, and including code snippets (Mozilla's Markdown guide).
    • Category: Assign a category (e.g., "New Feature," "Improvement," "Bug Fix").
  4. Publish: Review your entry and click "Publish." Your post will immediately appear on your public changelog feed.

Using the API

For automated or integrated workflows, you can publish a changelog entry using the Changelogs.md API. This typically involves making an HTTP POST request to a specific endpoint, authenticated with your API key.

While specific API endpoints and request bodies can vary, a common pattern involves sending JSON data to a publishing endpoint.

Example (conceptual) of an API request using curl:

curl -X POST \
  https://api.changelogs.md/v1/projects/{project_id}/entries \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "title": "API-Published Update",
    "content": "This is a **new** changelog entry published via the API. It supports [Markdown](https://developer.mozilla.org/en-US/docs/Web/Markdown).",
    "category": "New Feature",
    "status": "published"
  }'

Replace {project_id} with your actual project ID and YOUR_API_KEY with the API key obtained from your project settings. Refer to the Changelogs.md API documentation for exact endpoint details, required parameters, and response formats.

Common next steps

After successfully publishing your first changelog entry, consider these common next steps to further integrate and optimize your Changelogs.md setup:

  • Integrate Widgets: Embed your changelog feed directly into your website or application using the provided JavaScript widgets. This allows your users to view updates without leaving your platform (Changelogs.md widget integration guide).
  • Configure Notifications: Set up email or webhook notifications for new changelog posts. This can inform subscribers or trigger internal communication workflows.
  • Automate Publishing: Integrate changelog publishing into your CI/CD pipeline. This automates the process of announcing new releases as part of your deployment workflow. Tools like Google Cloud's CI/CD solutions or AWS CodePipeline often include steps for post-deployment actions.
  • Customize Appearance: Adjust the branding and styling of your changelog page to match your company's aesthetic. This is typically done within the project settings.
  • Manage Team Access: If on a paid plan, invite additional team members to collaborate on drafting and publishing changelog entries. Define roles and permissions for each member.
  • Explore Advanced Features: Investigate features such as scheduling posts, creating private changelogs for internal teams, or using custom domains for your changelog page.

Troubleshooting the first call

Encountering issues during your first API call or when publishing via the web interface is common. Here are some troubleshooting tips specific to Changelogs.md:

  • API Key Issues:
    • Incorrect Key: Double-check that you are using the correct API key for the specific project. API keys are project-specific.
    • Expired/Revoked Key: Ensure your API key is still active and hasn't been accidentally revoked or expired. Generate a new one if necessary.
    • Missing Bearer Prefix: For API requests, ensure the Authorization header uses the Bearer prefix followed by a space and your API key (e.g., Authorization: Bearer YOUR_API_KEY).
  • Project ID Mismatch: If using the API, verify that the project_id in your request URL matches an existing project accessible by your API key.
  • Incorrect Endpoint: Confirm that you are sending your request to the correct Changelogs.md API endpoint for publishing entries, as specified in their API reference.
  • Request Body Format:
    • JSON Structure: Ensure your request body is valid JSON and adheres to the required schema (e.g., correct field names like title, content, category).
    • Content Type Header: Make sure your Content-Type header is set to application/json.
  • Network or Firewall Issues: If you are making API calls from a restricted network, ensure that outgoing requests to api.changelogs.md are not blocked by a firewall or proxy.
  • Web Interface Publishing Errors:
    • Required Fields: Ensure all mandatory fields (like title and content) are filled before attempting to publish.
    • Connectivity: Verify your internet connection if the web interface is unresponsive during publishing.
  • Review Error Messages: Pay close attention to any error messages returned by the API or displayed in the web interface. These messages often provide specific details about what went wrong (e.g., "Unauthorized," "Invalid JSON," "Missing required field").
  • Consult Documentation: If issues persist, refer to the official Changelogs.md documentation or their support resources for more in-depth troubleshooting guides or to contact their support team.